mirror of
https://we.phorge.it/source/phorge.git
synced 2024-12-23 14:00:56 +01:00
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
This commit is contained in:
parent
c33f544e74
commit
7be671fb07
9 changed files with 140 additions and 118 deletions
|
@ -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));
|
||||
}
|
||||
|
||||
|
|
|
@ -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')
|
||||
|
|
|
@ -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();
|
||||
|
|
|
@ -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
|
||||
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:
|
||||
|
||||
|
|
|
@ -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
|
||||
"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
|
||||
|
|
|
@ -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
|
||||
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
|
||||
|
|
|
@ -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}.
|
|
@ -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
|
||||
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".
|
||||
|
||||
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`.
|
||||
| `regexp(/^release-/)` | Track all branches which start with `release-`.
|
||||
| `regexp(/^(?!temp-)/)` | Do not track branches which start with `temp-`.
|
||||
|
||||
|
||||
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.
|
||||
| `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
|
||||
|
|
81
src/docs/user/userguide/diffusion_permanent.diviner
Normal file
81
src/docs/user/userguide/diffusion_permanent.diviner
Normal file
|
@ -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}.
|
Loading…
Reference in a new issue