Page MenuHomePhabricator

Upgrading: Early 2020 Changes to Arcanist
Open, LowPublic

Description

The master branch of "Arcanist" is currently more unstable than usual. This task describes ongoing changes in master. You can switch to stable until the dust settles if these changes are impacting your workflow.

The minimum PHP version required to run Arcanist is now PHP 5.5, which was released seven years ago in 2013. Requiring this version of PHP allows Arcanist to use a few new language features, including: traits; yield; and finally. See T11968 for some details.

libphutil is no longer required. All the code in "libphutil/" which Arcanist requires has been merged into "arcanist/". "libphutil/" is now an empty repository with a README file. See T13395 for discussion. You can safely delete the "libphutil/" directory if it is empty and everything is working for you.

These flags to common arc workflows have been removed:

arc diff--plan-changes Removed, see T13010. Try --draft.
--preview Removed, see T13010. Try --draft.
--no-diff Removed, see T13010. Legacy flag.
--cache Removed, see T13010. Legacy flag.
arc lint--only-changed Removed. Try "warning" severity.
--only-new Removed. Almost never worked correctly.
--cache Removed. Legacy flag.

The way shell completion is configured has changed. If you use this feature, see below for update instructions.


These minor behaviors have also changed:

CLI/Scripting Behaviors

  • Configuration flags must now be specified before workflows. For example, arc --config x=y diff is valid, but arc diff --config x=y is not valid.
  • When stdout is not a TTY (usually, this means you're running arc in a script/non-interactive environment), command line flags must now be explicitly terminated with -- (the "end of flags" argument), even if there are no flags, or no arguments, or the command you are executing can not take flags or arguments or is otherwise completely unambiguous. See T13491 for more discussion.
  • arc no longer exits with error code 77 to indicate invalid flags.

Workflow: Alias

  • arc alias will no longer remove redundant flags. Previously, you could define arc draft -> arc diff --draft, then run arc draft --draft (which would naively resolve to arc diff --draft --draft) and have your duplicate flag cleaned up. This isn't safe in the general case and deviates from the explicit approach we generally prefer elsewhere.
  • You can now define aliases that resolve to other aliases, creating alias chains. Exceptionally useful! Thousands of users have demanded this feature!
  • alias is now a global workflow for any toolset.
  • Note that only "modern" workflows can be resolved by "arc alias".

Workflow: Help

  • The arc help --full flag no longer exists. arc help is more verbose than it was before.
  • Only modern workflows (not "classic" workflows) are currently
  • help is now a global workflow for any toolset.
  • Note that only "modern" workflows appear in "arc help".

Workflow: Liberate

  • arc liberate now liberates all libraries under the current working directory if given no arguments.
  • The flags --library-name, --force-update, --remap, and --verify no longer exist.
  • The flag --upgrade no longer exists. v1 libraries can no longer be upgraded to v2. If you have a library which is 5+ years old, remove all the __init__.php files and then just do a clean liberate on it.
  • The flag --all has been renamed to --clean (like make clean), for consistency with other commands and to disambiguate the new default behavior of rebuilding all libraries in subdirectories.

Workflow: Shell Complete

  • arc shell-complete now installs itself (when you run arc shell-complete).
  • You should edit anywhere you stuck the old source path/to/arcanist/.../bash-completion.sh line (like ~/.profile) and remove it. Then, run arc shell-complete to install the updated hook. Finally, start a new shell to pick up the changes.
  • The behavior of completion has changed somewhat, but probably not in any meaningful ways for most users.
  • Support for ZSH has been removed. This was contributed and I wasn't able to figure out how to make it work on master, so I suspect it may never have worked for more than one person in 2012. I'm open to restoring support if you're a ZSH wizard and can convince me that your implementation is correct and supportable, and it works out of the box for me by magic. See https://github.com/phacility/arcanist/pull/11 for the heady days of an upstream with low contribution barriers.
  • arc shell-complete is now a global workflow for any toolset.
  • Note that only "modern" workflows can be completed by arc shell-complete.

Workflow: Version

  • version is now a global workflow for any toolset. (But it isn't useful for other toolsets yet.)

.arcrc

  • The internal format of this file has changed, and it will now be written with keys at top level (instead of inside a "config" key). The old format will still be read. This only impacts you if you're manually reading .arcrc files, which you probably should not be.

Global Flags

  • Removed --conduit-version. We do capability testing, now.
  • Removed --conduit-timeout. Not clear this ever really had any callers.
  • Removed --skip-arcconfig. Unclear what this was for. FB only option because someone created an invalid file at /home/.arcconfig?

Configuration

  • Removed the arc.lint.cache configuration setting.
  • Removed the arcanist_configuration configuration setting. This is a legacy/FB-only option which doesn't fit into the roadmap.
  • The http.basicauth.user and http.basicauth.pass configuration options are no longer supported. These served a very niche use case. If you're a customer and need this, we can provide some similar capability via PhutilHTTPEngineExtension; file a support request.
  • The https.blindly-trust-domains configuration option is no longer supported. It's 2020, legitimate SSL is completely free now, and you should configure it properly. If you "need" this, you can implement it via PhutilHTTPEngineExtension.

Some internal APIs have also changed. This list is not exhaustive, but some of the most important changes are:

  • Future->resolve() no longer accepts a timeout. If you need to return execution to the caller after a certain amount of time, wrap the future in a FutureIterator and use setUpdateInterval().

And:

  • The preg_quote() lint rule has been removed. This had false positives on safe/correct use of preg_quote() with ( and ) as the expression delimiters, which is the modern coding style in this codebase.
  • The "use __CLASS__ instead of hard-coding a class name" lint rule no longer raises a warning if you use the class name as part of a longer string. So the string "Filesystem" (class name hard-coded as a string literal) still raises a warning if it appears in the class Filesystem, but the string "Filesystem path X does not exist." (class name used as an English word in a longer string) no longer raises this warning.

Event Timeline

epriestley triaged this task as Low priority.Thu, Feb 13, 1:49 PM
epriestley created this task.
epriestley updated the task description. (Show Details)Thu, Feb 13, 2:01 PM
epriestley updated the task description. (Show Details)Thu, Feb 13, 10:09 PM
epriestley updated the task description. (Show Details)Thu, Feb 13, 10:16 PM
epriestley updated the task description. (Show Details)Thu, Feb 13, 10:57 PM
epriestley updated the task description. (Show Details)Fri, Feb 14, 12:21 PM
cmmata added a subscriber: cmmata.Fri, Feb 14, 4:22 PM
epriestley updated the task description. (Show Details)Fri, Feb 14, 4:33 PM
epriestley updated the task description. (Show Details)Fri, Feb 14, 4:41 PM
epriestley updated the task description. (Show Details)Fri, Feb 14, 4:46 PM
epriestley updated the task description. (Show Details)Fri, Feb 14, 4:50 PM
epriestley updated the task description. (Show Details)Fri, Feb 14, 5:07 PM
epriestley updated the task description. (Show Details)Sat, Feb 15, 5:58 PM
epriestley updated the task description. (Show Details)Sat, Feb 15, 6:04 PM
epriestley updated the task description. (Show Details)Mon, Feb 17, 5:22 PM
epriestley updated the task description. (Show Details)
epriestley updated the task description. (Show Details)Wed, Feb 26, 4:38 PM
epriestley updated the task description. (Show Details)Wed, Feb 26, 4:52 PM
epriestley updated the task description. (Show Details)
jnv added a subscriber: jnv.Fri, Feb 28, 3:13 PM