Page MenuHomePhabricator

Upcoming: Changes to Arcanist
Closed, ResolvedPublic


This task discusses upcoming changes to Arcanist. There are several parallel efforts which are likely to happen around the same time and impact users who have customized code or written extensions. This discusses what to expect.

Briefly, the planned changes are:

  • New Package Management System (T5055): We are introducing a package management system for arc to make distributing and updating extensions easier.
  • Modularization of Lint and Unit Bindings (T10038): We plan to make it easier to write lint and unit bindings, and easier to distribute and update them as packages, then move bindings which we do not plan to maintain ourselves out of the upstream. We're doing a bad job of maintaining these today and expect this will improve the state of the world significantly for everyone.
  • Usability Improvments to arc diff (T6072): Users have ongoing difficulty understanding and predicting the behavior of arc diff. We plan to make changes to try to improve this.
  • Rewrite of Workflows and Events (T10329): arc workflows are currently difficult to customize and have some technical debt related to the existing hooks. We plan to significantly rewrite how this code is structured to make it easier to work with and extend.
  • Improved Windows Support (T8298, etc): arc has a number of compatibility issues on Windows, some of which are severe.
  • Update to Modern APIs (T10945, etc): More modern versions of many Phabricator APIs are now available. Since some of the other changes are somewhat-breaking, this is a good opportunity to do API updates concurrently and limit how many upgrades users need to make.

In slightly more detail:

Package Management: One of the biggest overall issues with arc is that there's no good way to distribute or update extensions unless all of your developers run a standard environment. Although environment standardization is common at large companies, it is much less common at smaller companies and virtually unheard of in open source projects. To remedy this, we are providing a package management system so users can publish, install, and update extensions.

This system will be fairly simple at first and mostly just make it easier to package and install arc plugins. In the long run, we also expect to distribute third-party Phabricator applications, but this is some ways away. There is more technical detail in T5055.

Today, this will primarily affect lint bindings and unit bindings, which are in bad shape. Since it's hard to distribute or update extensions, there was historically a strong incentive to get whatever you could into the upstream. However, we have neither the expertise nor resources to maintain bindings for every linter in existence, which has turned the upstream into a crumbling ruin of poorly maintained lint and unit bindings. This is discussed in greater detail in T10038. Once the package manager is stable, I expect to make it easier to write lint/unit bindings and then start removing unmaintained bindings from the upstream (either entirely, or into packages which we try to pawn off on someone). Ideally, third parties who are better equipped to maintain them will take them over and publish them as packages.

Packages will also provide a better way to distribute and update arc workflow extensions.

Workflows: Today, workflows are theoretically extensible with a handful of very old event hooks. However, these event hooks are a pain to set up and mostly don't do anything useful. Many of the use cases they served were one-offs from a long-ago era where installs faced a low barrier to upstreaming weird stuff, and about half of them serve niche Facebook-specific use cases.

In the modern era, we have now identified a smaller set of useful integration points in the diff workflow, including:

  • (T9223) A hook for running a unified build/unit command, like gradle.
  • (T10622) A hook for making commit message suggestions (like suggesting reviewers, or inferring the JIRA task name from the branch name).
  • (T5064) A hook for running pre-land steps, like generating artifacts or checking that the operation has an "all clear" from the build system.

Beyond this, both the event code and general workflow code are fairly unmodern (vaguely, T7487) and not especially well-structured. This is a good opportunity to improve them, restructure code which can have a better home, and attempt to prepare for a future with greater modularity -- for example, by exposing more functionality as reusable components (like T11355). This is discussed in more detail in T10329.


For most users, these changes probably won't have much impact. However:

  • There may be points at which you are required to upgrade Phabricator or Arcanist to keep them compatible, if you upgrade one without upgrading the other.
  • The behavior of arc diff will change slightly. It should become easier to use in most cases, but some workflows may also be disrupted (for example, we are likely to remove default-relative-commit completely in favor of the equivalent but substantially more powerful base option).
  • If you rely on upstream linters or unit test bindings which we don't retain as part of the upstream, you may need to configure your projects to pull the relevant packages in once the bindings leave the upstream. This will likely be a small configuration change amounting to "packages": ["xyzlint", "abcunit"].
  • If you have custom workflows, they will likely require minor adjustments to the API. These adjustments are likely to mostly be cosmetic.
  • If you have custom event hooks, they will likely require significant rework. We expect very few installs to have custom event hooks.

This is a large amount of work, and big parts of this are likely to have long feedback/stabilization cycles where we kind of wait and see if things fall apart or we broke all users forever before writing more code. We've begun chipping away at it and some small pieces are prioritized (see Prioritized), but it is likely to stretch over many months.

Related Objects

Event Timeline

epriestley closed this task as Resolved.EditedSep 27 2018, 3:11 PM
epriestley claimed this task.

This has effectively expanded in scope into T13098.

For most users, these changes probably won't have much impact.

This is likely no longer true.