Page MenuHomePhabricator
Files F15344831

D20434.id48787.diff
No OneTemporary
Actions

D20434.id48787.diff
View Options

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}.

File Metadata

Mime Type
text/plain
Expires
Tue, Mar 11, 6:55 AM (2 w, 13 h ago)
Storage Engine
blob
Storage Format
Encrypted (AES-256-CBC)
Storage Handle
7506913
Default Alt Text
D20434.id48787.diff (15 KB)

Event Timeline

Phabricator · Built by Phacility