diff --git a/src/applications/diffusion/editor/DiffusionCommitEditEngine.php b/src/applications/diffusion/editor/DiffusionCommitEditEngine.php --- a/src/applications/diffusion/editor/DiffusionCommitEditEngine.php +++ b/src/applications/diffusion/editor/DiffusionCommitEditEngine.php @@ -136,7 +136,8 @@ 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 @@ pht('Learn More')); $fields[] = id(new PhabricatorStaticEditField()) - ->setLabel(pht('Autoclose?')) + ->setLabel(pht('Published?')) ->setValue(array($desc, " \xC2\xB7 ", $doc_link)); } diff --git a/src/applications/diffusion/view/DiffusionBranchListView.php b/src/applications/diffusion/view/DiffusionBranchListView.php --- a/src/applications/diffusion/view/DiffusionBranchListView.php +++ b/src/applications/diffusion/view/DiffusionBranchListView.php @@ -32,7 +32,6 @@ Javelin::initBehavior('phabricator-tooltips'); - $doc_href = PhabricatorEnv::getDoclink('Diffusion User Guide: Autoclose'); $list = id(new PHUIObjectItemListView()) ->setFlush(true) ->addClass('diffusion-history-list') diff --git a/src/applications/diffusion/view/DiffusionBranchTableView.php b/src/applications/diffusion/view/DiffusionBranchTableView.php --- a/src/applications/diffusion/view/DiffusionBranchTableView.php +++ b/src/applications/diffusion/view/DiffusionBranchTableView.php @@ -31,7 +31,8 @@ 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(); diff --git a/src/docs/user/field/repository_imports.diviner b/src/docs/user/field/repository_imports.diviner --- a/src/docs/user/field/repository_imports.diviner +++ b/src/docs/user/field/repository_imports.diviner @@ -30,9 +30,9 @@ 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 -email, and apply Owners rules. You can learn more about some of these steps in -@{article:Diffusion User Guide: Autoclose}. +and update related objects, cache changes, trigger Herald, publish feed stories +and email, and apply Owners rules. You can learn more about some of these steps +in @{article:Diffusion User Guide: Permanent Refs}. Specifically, the import pipeline has four steps: diff --git a/src/docs/user/userguide/arcanist_diff.diviner b/src/docs/user/userguide/arcanist_diff.diviner --- a/src/docs/user/userguide/arcanist_diff.diviner +++ b/src/docs/user/userguide/arcanist_diff.diviner @@ -167,11 +167,10 @@ 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 -"Autoclose" in the Repository configuration.) +identifiers in commit messages. 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 diff --git a/src/docs/user/userguide/diffusion.diviner b/src/docs/user/userguide/diffusion.diviner --- a/src/docs/user/userguide/diffusion.diviner +++ b/src/docs/user/userguide/diffusion.diviner @@ -86,8 +86,8 @@ If you're having trouble getting things working, these topic guides may be helpful: - - get details about automatically closing tasks and revisions in response - to commits in @{article:Diffusion User Guide: Autoclose}; or + - get details about automatically taking actions in response to commits in + @{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 diff --git a/src/docs/user/userguide/diffusion_autoclose.diviner b/src/docs/user/userguide/diffusion_autoclose.diviner deleted file mode 100644 --- a/src/docs/user/userguide/diffusion_autoclose.diviner +++ /dev/null @@ -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}. diff --git a/src/docs/user/userguide/diffusion_managing.diviner b/src/docs/user/userguide/diffusion_managing.diviner --- a/src/docs/user/userguide/diffusion_managing.diviner +++ b/src/docs/user/userguide/diffusion_managing.diviner @@ -137,6 +137,19 @@ 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,38 +300,50 @@ 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 -configure **Track Only**. Other branches will be ignored. If you do not specify -any branches, all branches are tracked. +**Fetch Refs**: In Git, if you are observing a remote repository, you can +specify that you only want to fetch a subset of refs using "Fetch Refs". -When specifying branches, you should enter one branch name per line. You can -use regular expressions to match branches by wrapping an expression in -`regexp(...)`. For example: +Normally, all refs (`refs/*`) are fetched. This means all branches, all tags, +and all other refs. -| Example | Effect | -|---------|--------| -| `master` | Track only `master`. -| `regexp(/^release-/)` | Track all branches which start with `release-`. -| `regexp(/^(?!temp-)/)` | Do not track branches which start with `temp-`. +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 +``` -Actions -====== +You can fetch all branches and tags (but ignore other refs) like this: -The **Actions** panel can configure notifications and publishing behavior. +``` +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. -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. +**Permanent Refs**: To learn more about permanent refs, see: -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. + - @{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 +`regexp(...)`. For example: + +| Example | Effect | +|---------|--------| +| `master` | Only the `master` branch is a permanent ref. +| `regexp(/^release-/)` | Branches are permanent if they start with `release-`. +| `regexp(/^(?!temp-)/)` | Branches named `temp-` are not permanent. Staging Area diff --git a/src/docs/user/userguide/diffusion_permanent.diviner b/src/docs/user/userguide/diffusion_permanent.diviner new file mode 100644 --- /dev/null +++ b/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}.