Update "Autoclose" documentation to focus on "Permanent Refs" instead

Summary:
Depends on D20433. Ref T13277. Since "Autoclose" no longer exists, update the documentation.

Currently, this documentation focuses a lot on troubleshooting because users historically had a lot of trouble with figuring out why things were or were not autoclosing. I haven't seen any real confusion about this in years, so I suspect we may have improved the import pipeline and/or UI to make this less of a problem.

It's also possible that this document "fixed" the problem, but usually I expect a documentation fix to not affect the frequency of reports, just make them easier to resolve, so I doubt it.

If unclear things remain //and// documentation really did fix it, maybe we can fix the issues. Or we can just put the troubleshooting documentation back.

Test Plan: Read documentation.

Reviewers: amckinley

Reviewed By: amckinley

Maniphest Tasks: T13277

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

src/applications/diffusion/editor/DiffusionCommitEditEngine.php

@@ -136,7 +136,8 @@ final class DiffusionCommitEditEngine
           break;
       }
 
-      $doc_href = PhabricatorEnv::getDoclink('Diffusion User Guide: Autoclose');
+      $doc_href = PhabricatorEnv::getDoclink(
+        'Diffusion User Guide: Permanent Refs');
       $doc_link = phutil_tag(
         'a',
         array(
@@ -146,7 +147,7 @@ final class DiffusionCommitEditEngine
         pht('Learn More'));
 
         $fields[] = id(new PhabricatorStaticEditField())
-          ->setLabel(pht('Autoclose?'))
+          ->setLabel(pht('Published?'))
           ->setValue(array($desc, " \xC2\xB7 ", $doc_link));
     }
 

src/applications/diffusion/view/DiffusionBranchListView.php

@@ -32,7 +32,6 @@ final class DiffusionBranchListView extends DiffusionView {
 
     Javelin::initBehavior('phabricator-tooltips');
 
-    $doc_href = PhabricatorEnv::getDoclink('Diffusion User Guide: Autoclose');
     $list = id(new PHUIObjectItemListView())
       ->setFlush(true)
       ->addClass('diffusion-history-list')

src/applications/diffusion/view/DiffusionBranchTableView.php

@@ -31,7 +31,8 @@ final class DiffusionBranchTableView extends DiffusionView {
 
     Javelin::initBehavior('phabricator-tooltips');
 
-    $doc_href = PhabricatorEnv::getDoclink('Diffusion User Guide: Autoclose');
+    $doc_href = PhabricatorEnv::getDoclink(
+      'Diffusion User Guide: Permanent Refs');
 
     $rows = array();
     $rowc = array();

src/docs/user/field/repository_imports.diviner

@@ -30,9 +30,9 @@ updates in @{article:Diffusion User Guide: Repository Updates}.
 
 After commits are discovered, background tasks are queued to actually import
 commits. These tasks do things like look at commit messages, trigger mentions
-and autoclose rules, cache changes, trigger Herald, publish feed stories and
+and update related objects, cache changes, trigger Herald, publish feed stories
-email, and apply Owners rules. You can learn more about some of these steps in
+and email, and apply Owners rules. You can learn more about some of these steps
-@{article:Diffusion User Guide: Autoclose}.
+in @{article:Diffusion User Guide: Permanent Refs}.
 
 Specifically, the import pipeline has four steps:
 

src/docs/user/userguide/arcanist_diff.diviner

@@ -167,11 +167,10 @@ You can use `arc help <command>` for detailed help with any of these.
 Differential will make a guess about a next step on accepted revisions, but it
 may not be the best next step for your workflow.
 
-Phabricator will also automatically close revisions, if the changes are pushed
+Phabricator will also automatically close revisions if the changes are pushed
 to a repository that is tracked in Diffusion. Specifically, it will close
 revisions based on commit and tree hashes, and `Differential Revision`
-identifiers in commit messages. (You can disable this feature by disabling
+identifiers in commit messages.
-"Autoclose" in the Repository configuration.)
 
 If you push to an untracked repository (or `arc` can't figure out that it's
 tracked), `arc land`, `arc amend` and `arc commit` will implicitly run

src/docs/user/userguide/diffusion.diviner

@@ -86,8 +86,8 @@ Continue by:
 If you're having trouble getting things working, these topic guides may be
 helpful:
 
-  - get details about automatically closing tasks and revisions in response
+  - get details about automatically taking actions in response to commits in
-    to commits in @{article:Diffusion User Guide: Autoclose}; or
+    @{article:Diffusion User Guide: Permanent Refs}; or
   - understand how Phabricator updates repositories with
     @{article:Diffusion User Guide: Repository Updates}; or
   - fix issues with repository imports with

src/docs/user/userguide/diffusion_autoclose.diviner

@@ -1,84 +0,0 @@
-@title Diffusion User Guide: Autoclose
-@group userguide
-
-Explains when Diffusion will close tasks and revisions upon discovery of related
-commits.
-
-Overview
-========
-
-Diffusion can close tasks and revisions when related commits appear in a
-repository. For example, if you make a commit with `Fixes T123` in the commit
-message, Diffusion will close the task `T123`.
-
-This document explains how autoclose works, how to configure it, and how to
-troubleshoot it.
-
-Troubleshooting Autoclose
-=========================
-
-You can check if a branch is currently configured to autoclose on the
-management page for the given repository under the branches menu item.
-You should see one of these statuses next to the name of the branch:
-
-  - **Autoclose On** Autoclose is active for this branch.
-  - **Repository Importing** This repository is still importing.
-    Autoclose does not activate until a repository finishes importing for the
-    first time. This prevents situations where you import a repository and
-    accidentally close hundreds of related objects during import. Autoclose
-    will activate for new commits after the initial import completes.
-  - **Tracking Off** This branch is not tracked. Because it
-    is not tracked, commits on it won't be seen and won't be discovered.
-  - **Autoclose Off** Autoclose is not enabled for
-    this branch. You can adjust which branches autoclose in **Edit Repository**.
-    This option is only available in Git.
-
-If a branch is in good shape, you can check a specific commit by viewing it
-in the web UI and clicking **Edit Commit**. There should be an **Autoclose?**
-field visible in the form, with possible values listed below.
-
-Note that this field records the state of the world at the time the commit was
-processed, and does not necessarily reflect the current state of the world.
-For example, if a commit did not trigger autoclose because it was processed
-during initial import, the field will still show **No, Repository Importing**
-even after import completes. This means that the commit did not trigger
-autoclose because the repository was importing at the time it was processed,
-not necessarily that the repository is still importing.
-
-  - **Yes** At the time the commit was imported, autoclose triggered and
-    Phabricator attempted to close related objects.
-  - **No, Repository Importing** At the time the commit was processed, the
-    repository was still importing. Autoclose does not activate until a
-    repository fully imports for the first time.
-  - **No, Autoclose Disabled** At the time the commit was processed, the
-    repository had autoclose disabled.
-  - **No, Not On Autoclose Branch** At the time the commit was processed,
-    no containing branch was configured to autoclose.
-  - //Field Not Present// This commit was processed before we implemented
-    this diagnostic feature, and no information is available.
-
-
-Manually Closing Revisions
-==========================
-
-If autoclose didn't activate for some reason and you want to manually close
-revisions, you can do so in several ways:
-
-**Close Revision**: The revision author can use the "Close Revision" action
-from the web UI, located in the action dropdown on the revision page (where
-reviewers would "Accept Revision" or "Request Changes").
-
-`differential.always-allow-close`: If you set this option in {nav Config},
-any user can take the "Close Revision" action in the web UI.
-
-`arc close-revision`: You can close revisions from the command line by using
-`arc close-revision`.
-
-
-Next Steps
-==========
-
-Continue by:
-
-  - troubleshooting in greater depth with
-    @{article:Troubleshooting Repository Imports}.

src/docs/user/userguide/diffusion_managing.diviner

@@ -137,6 +137,19 @@ can not prevent dangerous changes in a remote repository it is merely
 observing.
 
 
+Basics: Disable Publishing
+==========================
+
+You can disable publishing for a repository. For more details on what this
+means, see @{article:Diffusion User Guide: Permanent Refs}.
+
+This is primarily useful if you need to perform major maintenance on a
+repository (like rewriting a large part of the repository history) and you
+don't want the maintenance to generate a large volume of email and
+notifications. You can disable publishing, apply major changes, wait for the
+new changes to import, and then reactivate publishing.
+
+
 Basics: Deactivate Repository
 =============================
 
@@ -287,13 +300,40 @@ branches.
 This panel is not available for Subversion repositories, because Subversion
 does not have formal branches.
 
-You can configure **Default Branch**. This controls which branch is shown by
+You can configure a **Default Branch**. This controls which branch is shown by
 default in the UI. If no branch is provided, Phabricator will use `master` in
 Git and `default` in Mercurial.
 
-If you want Diffusion to ignore some branches in the repository, you can
+**Fetch Refs**: In Git, if you are observing a remote repository, you can
-configure **Track Only**. Other branches will be ignored. If you do not specify
+specify that you only want to fetch a subset of refs using "Fetch Refs".
-any branches, all branches are tracked.
+
+Normally, all refs (`refs/*`) are fetched. This means all branches, all tags,
+and all other refs.
+
+If you want to fetch only a few specific branches, you can list only those
+branches. For example, this will fetch only the branch "master":
+
+```
+refs/heads/master
+```
+
+You can fetch all branches and tags (but ignore other refs) like this:
+
+```
+refs/heads/*
+refs/tags/*
+```
+
+This may be useful if the remote is on a service like GitHub, GitLab, or
+Gerrit and uses custom refs (like `refs/pull/` or `refs/changes/`) to store
+metadata that you don't want to bring into Phabricator.
+
+**Permanent Refs**: To learn more about permanent refs, see:
+
+  - @{article:Diffusion User Guide: Permanent Refs}
+
+By default, Phabricator considers all branches to be permanent refs. If you
+only want some branches to be treated as permanent refs, specify them here.
 
 When specifying branches, you should enter one branch name per line. You can
 use regular expressions to match branches by wrapping an expression in
@@ -301,24 +341,9 @@ use regular expressions to match branches by wrapping an expression in
 
 | Example | Effect |
 |---------|--------|
-| `master` | Track only `master`.
+| `master` | Only the `master` branch is a permanent ref.
-| `regexp(/^release-/)` | Track all branches which start with `release-`.
+| `regexp(/^release-/)` | Branches are permanent if they start with `release-`.
-| `regexp(/^(?!temp-)/)` | Do not track branches which start with `temp-`.
+| `regexp(/^(?!temp-)/)` | Branches named `temp-` are not permanent.
-
-
-Actions
-======
-
-The **Actions** panel can configure notifications and publishing behavior.
-
-Normally, Phabricator publishes notifications when it discovers new commits.
-You can disable publishing for a repository by turning off **Publish/Notify**.
-This will disable notifications, feed, and Herald (including audits and build
-plans) for this repository.
-
-When Phabricator discovers a new commit, it can automatically close associated
-revisions and tasks. If you don't want Phabricator to close objects when it
-discovers new commits, disable **Autoclose** for the repository.
 
 
 Staging Area

src/docs/user/userguide/diffusion_permanent.diviner

@@ -0,0 +1,81 @@
+@title Diffusion User Guide: Permanent Refs
+@group userguide
+
+Explains when Diffusion will take actions in response to discovering commits.
+
+Overview
+========
+
+Diffusion can close tasks and revisions and take other actions when commits
+appear in a repository (either because they were pushed to Phabricator, or
+because they were pushed to some remote which Phabricator is observing).
+
+This document explains when Diffusion acts on commits and how to configure this
+behavior.
+
+
+Publishing Commits
+==================
+
+Diffusion distinguishes between "pushed" and "published" commits.
+
+Not all commits that are pushed to a repository are destined for greatness:
+for example, many tools push temporary commits to secret places like
+`refs/pull/123`, `refs/notes/*`, or `refs/changes/12/345678/1`.
+
+Sometimes, human users intentionally push changes to branches like
+"tmp-hack-ignore-123". This is formally discouraged by Phabricator, but the
+practice is so widespread that we've given up trying to stop anyone from doing
+it.
+
+Phabricator will import these commits and create pages for them so you can view
+them in the web UI and link to them, but does not take any other actions until
+they are "published".
+
+A commit is "published" when it becomes reachable from a permanent ref. By
+default, all branches are permanent refs, so pushing a commit to "master" will
+publish it, but pushing a commit to `refs/pull/123` (either directly, or by
+using a tool like GitHub) will not.
+
+Usually, commits are published by pushing them directly to a permanent branch
+like "master", or by merging a temporary branch into a permanent branch.
+
+When a commit is published, Phabricator acts on it and:
+
+  - sends email;
+  - delivers notifications;
+  - publishes a feed story;
+  - triggers Audits;
+  - runs Herald rules;
+  - updates mentioned objects;
+  - closes referenced tasks; and
+  - closes associated revisions.
+
+
+Configuring Repositories
+========================
+
+You can control publishing behavior in two primary ways: by configuring
+which refs are considered to be permanent refs, and by disabling publishing
+entirely.
+
+By default, all branches are considered permanent refs and all other refs
+(including tags and other arbitrary custom refs) are considered nonpermanent.
+This means that, by default, pushing commits to a branch like
+"tmp-hack-ignore-123" will publish those commits.
+
+If you want to be free to push commits to temporary branches like this and
+only want commits on certain branches (like "master") to be published,
+configure which refs are treated as permanent by editing
+{nav Branches > Permanent Refs} from the "Manage" page of the repository.
+
+To disable publishing entirely, select {nav Basics > Disable Publishing}.
+
+
+Next Steps
+==========
+
+Continue by:
+
+  - troubleshooting in greater depth with
+    @{article:Troubleshooting Repository Imports}.