Update documentation for D3045

Summary: Some minor updates for changes in D3045 and clarity.

Test Plan: Read documentation.

Reviewers: dschleimer, bos, btrahan, vrana

Reviewed By: dschleimer

CC: aran, cbiesinger

Maniphest Tasks: T1507, T1546

Differential Revision: https://secure.phabricator.com/D3046

src/docs/userguide/arcanist_commit_ranges.diviner

@@ -55,15 +55,15 @@ A rule may //match//, meaning that it identifies some valid commit in the
 working copy, or //fail//, meaning that it does not identify a valid commit. For
 instance, the rule `arc:upstream` will //match// if the current Git branch
 tracks an upstream branch, but //fail// if the current Git branch does not track
-an upstream branch. When a rule fails, processing continues with the next rule.
-Some rules can never match but produce useful side effects instead. These are
-described below.
+an upstream branch, or the working copy isn't a Git working copy. When a rule
+fails, processing continues with the next rule. Some rules can never match but
+produce useful side effects instead. These are described below.
 
 A //ruleset// is a comma-separated list of rules:
 
   arc:upstream, arc:prompt
 
-`arc` reads four rulesets:
+`arc` reads five rulesets:
 
   # `args`, specified with `--base <ruleset>` on the command line when you run
     a command. This ruleset is processed first.
@@ -278,7 +278,7 @@ it has a different bookmark. When run from `C3`, it will select `C2` and `C3`.
 
 However, this rule will select the wrong commit range in some cases (for
 example, if the "zebra" bookmark has moved on, the rule will no longer stop on
-`C3` and will select `C2`, `C3` and `C4` when run from `C4).
+`C3` and will select `C2`, `C3` and `C4` when run from `C4`).
 
 == arc:exec(*) ==
 

src/docs/userguide/arcanist_lint_unit.diviner

@@ -38,7 +38,7 @@ then make the library loadable by adding it to your ##.arcconfig## like this:
 
   {
     // ...
-    "phutil_libraries" : [
+    "load" : [
       // ...
       "/path/to/my/library", // Absolute path
       "support/arcanist",    // Relative path in this project

src/docs/userguide/arcanist_new_project.diviner

@@ -86,35 +86,35 @@ Other options include:
   - **arcanist_configuration**: the name of a subclass of
     @{class@arcanist:ArcanistConfiguration} which can add new command flags for
     this project or provide entirely new commands.
-  - **copyright_holder**: used by @{class@arcanist:ArcanistLicenseLinter} to
-    apply license notices to source files.
-  - **immutable_history**: controls how `arc diff` behaves in Git. See below.
-  - **phutil_libraries**: map of additional Phutil libraries to load at startup.
+  - **history.immutable**: controls how `arc diff` and some other commands
+    behave in Git and Mercurial. See below.
+  - **load**: list of additional Phutil libraries to load at startup.
     See below for details about path resolution, or see
     @{article:libphutil Libraries User Guide} for a general introduction to
     libphutil libraries.
 
-= Immutable History =
+= History Mutability =
 
-There are a lot of ways to use git, and Arcanist is flexible enough to handle
-several of them. Git workflows divide into two major groups based on your
-**doctrine of history mutability**.
+Arcanist workflows run in two broad modes: either history is //mutable// or
+//immutable//. Under a //mutable// history, `arc` commands may rewrite the
+working copy history; under an //immutable// history, they may not.
 
-Choose a **history mutability doctrine** by setting ##"immutable_history"## in
-your ##.arcconfig##. Valid values are ##true## to enforce a **conservative
-history mutability doctrine** or ##false## to enforce a **liberal history
-mutability doctrine**. The default is ##false##.
+You control history mutability by setting `history.immutable` to `true` or
+`false` in your configuration. By default, it is `false` in Git (i.e.,
+//mutable//) and `true` in Mercurial (i.e., //immutable//). The sections below
+explain how these settings affect workflows.
 
-A **liberal history mutability doctrine** means you rewrite local history. You
-develop in feature branches, but squash or amend before pushing by using ##git
-commit --amend## or ##git rebase -i##. Generally, one idea in the remote is
-represented by one commit.
+== History Mutability: Git ==
 
-A **conservative history mutability doctrine** means that you do not rewrite
-local history. This is similar to how Mercurial works. You develop in feature
-branches and push them without squashing commits. You do not use ##git commit
---amend## or ##git rebase -i##. Generally, one idea in the remote is represented
-by many commits.
+In a workflow with //mutable// history, you rewrite local history. You develop
+in feature branches, but squash or amend before pushing by using ##git commit
+--amend##, ##git rebase -i##, or `git merge --squash`. Generally, one idea in
+the remote is represented by one commit.
+
+In a workflow with //immutable// history, you do not rewrite local history. You
+develop in feature branches and push them without squashing commits. You do not
+use ##git commit --amend## or ##git rebase -i##. Generally, one idea in the
+remote is represented by many commits.
 
 Practically, these are the differences you'll see based on your setting:
 
@@ -123,11 +123,30 @@ Practically, these are the differences you'll see based on your setting:
     - `arc diff` will amend the commit message in HEAD after creating a
       revision.
     - `arc land` will default to the `--squash` strategy.
+    - `arc amend` will amend the commit message in HEAD with information from
+      the corresponding or specified Differential revision.
   - **Immutable**
     - `arc diff` will abort if it makes lint changes.
     - `arc diff` will not amend the commit message in HEAD after creating a
       revision.
     - `arc land` will default to the `--merge` strategy.
+    - `arc amend` will exit with an error message.
+
+== History Mutability: Mercurial ==
+
+Before version 2.2, stock Mercurial has no history mutation commands, so
+this setting has no effect. With Mercurial 2.2. or newer, making history
+//mutable// means:
+
+  - **Mutable** (versions 2.2 and newer)
+    - `arc diff` will amend the commit message in `.` after creating a
+      revision.
+    - `arc amend` will amend the commit message in `.` with information from
+      the corresponding or specified Differential revision.
+  - **Immutable** (or versions prior to 2.2)
+    - `arc diff` will not amend the commit message in `.` after creating a
+      revision.
+    - `arc amend` will exit with an error message.
 
 = How Libraries Are Located =
 
@@ -136,9 +155,9 @@ relative path like this:
 
   {
     ...
-    "load_libraries": {
-      "examplelib" : "examplelib/src"
-    },
+    "load": [
+      "examplelib/src"
+    ],
     ...
   }
 

src/docs/userguide/libraries.diviner

@@ -84,9 +84,9 @@ Phabricator. For example, you might write this file to
 
   {
     "project_id" : "libcustom",
-    "phutil_libraries" : {
-      "phabricator" : "phabricator/src/"
-    }
+    "load" : [
+      "phabricator/src/"
+    ]
   }
 
 For details on creating a ##.arcconfig##, see