@recaptime-dev's working patches + fork for Phorge, a community fork of Phabricator. (Upstream dev and stable branches are at upstream/main and upstream/stable respectively.)
hq.recaptime.dev/wiki/Phorge
phorge
phabricator
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
+140
-118
+3
-2
src/applications/diffusion/editor/DiffusionCommitEditEngine.php
+3
-2
src/applications/diffusion/editor/DiffusionCommitEditEngine.php
···
136
136
break;
137
137
}
138
138
139
-
$doc_href = PhabricatorEnv::getDoclink('Diffusion User Guide: Autoclose');
139
+
$doc_href = PhabricatorEnv::getDoclink(
140
+
'Diffusion User Guide: Permanent Refs');
140
141
$doc_link = phutil_tag(
141
142
'a',
142
143
array(
···
146
147
pht('Learn More'));
147
148
148
149
$fields[] = id(new PhabricatorStaticEditField())
149
-
->setLabel(pht('Autoclose?'))
150
+
->setLabel(pht('Published?'))
150
151
->setValue(array($desc, " \xC2\xB7 ", $doc_link));
151
152
}
152
153
-1
src/applications/diffusion/view/DiffusionBranchListView.php
-1
src/applications/diffusion/view/DiffusionBranchListView.php
+2
-1
src/applications/diffusion/view/DiffusionBranchTableView.php
+2
-1
src/applications/diffusion/view/DiffusionBranchTableView.php
+3
-3
src/docs/user/field/repository_imports.diviner
+3
-3
src/docs/user/field/repository_imports.diviner
···
30
30
31
31
After commits are discovered, background tasks are queued to actually import
32
32
commits. These tasks do things like look at commit messages, trigger mentions
33
-
and autoclose rules, cache changes, trigger Herald, publish feed stories and
34
-
email, and apply Owners rules. You can learn more about some of these steps in
35
-
@{article:Diffusion User Guide: Autoclose}.
33
+
and update related objects, cache changes, trigger Herald, publish feed stories
34
+
and email, and apply Owners rules. You can learn more about some of these steps
35
+
in @{article:Diffusion User Guide: Permanent Refs}.
36
36
37
37
Specifically, the import pipeline has four steps:
38
38
+2
-3
src/docs/user/userguide/arcanist_diff.diviner
+2
-3
src/docs/user/userguide/arcanist_diff.diviner
···
167
167
Differential will make a guess about a next step on accepted revisions, but it
168
168
may not be the best next step for your workflow.
169
169
170
-
Phabricator will also automatically close revisions, if the changes are pushed
170
+
Phabricator will also automatically close revisions if the changes are pushed
171
171
to a repository that is tracked in Diffusion. Specifically, it will close
172
172
revisions based on commit and tree hashes, and `Differential Revision`
173
-
identifiers in commit messages. (You can disable this feature by disabling
174
-
"Autoclose" in the Repository configuration.)
173
+
identifiers in commit messages.
175
174
176
175
If you push to an untracked repository (or `arc` can't figure out that it's
177
176
tracked), `arc land`, `arc amend` and `arc commit` will implicitly run
+2
-2
src/docs/user/userguide/diffusion.diviner
+2
-2
src/docs/user/userguide/diffusion.diviner
···
86
86
If you're having trouble getting things working, these topic guides may be
87
87
helpful:
88
88
89
-
- get details about automatically closing tasks and revisions in response
90
-
to commits in @{article:Diffusion User Guide: Autoclose}; or
89
+
- get details about automatically taking actions in response to commits in
90
+
@{article:Diffusion User Guide: Permanent Refs}; or
91
91
- understand how Phabricator updates repositories with
92
92
@{article:Diffusion User Guide: Repository Updates}; or
93
93
- fix issues with repository imports with
-84
src/docs/user/userguide/diffusion_autoclose.diviner
-84
src/docs/user/userguide/diffusion_autoclose.diviner
···
1
-
@title Diffusion User Guide: Autoclose
2
-
@group userguide
3
-
4
-
Explains when Diffusion will close tasks and revisions upon discovery of related
5
-
commits.
6
-
7
-
Overview
8
-
========
9
-
10
-
Diffusion can close tasks and revisions when related commits appear in a
11
-
repository. For example, if you make a commit with `Fixes T123` in the commit
12
-
message, Diffusion will close the task `T123`.
13
-
14
-
This document explains how autoclose works, how to configure it, and how to
15
-
troubleshoot it.
16
-
17
-
Troubleshooting Autoclose
18
-
=========================
19
-
20
-
You can check if a branch is currently configured to autoclose on the
21
-
management page for the given repository under the branches menu item.
22
-
You should see one of these statuses next to the name of the branch:
23
-
24
-
- **Autoclose On** Autoclose is active for this branch.
25
-
- **Repository Importing** This repository is still importing.
26
-
Autoclose does not activate until a repository finishes importing for the
27
-
first time. This prevents situations where you import a repository and
28
-
accidentally close hundreds of related objects during import. Autoclose
29
-
will activate for new commits after the initial import completes.
30
-
- **Tracking Off** This branch is not tracked. Because it
31
-
is not tracked, commits on it won't be seen and won't be discovered.
32
-
- **Autoclose Off** Autoclose is not enabled for
33
-
this branch. You can adjust which branches autoclose in **Edit Repository**.
34
-
This option is only available in Git.
35
-
36
-
If a branch is in good shape, you can check a specific commit by viewing it
37
-
in the web UI and clicking **Edit Commit**. There should be an **Autoclose?**
38
-
field visible in the form, with possible values listed below.
39
-
40
-
Note that this field records the state of the world at the time the commit was
41
-
processed, and does not necessarily reflect the current state of the world.
42
-
For example, if a commit did not trigger autoclose because it was processed
43
-
during initial import, the field will still show **No, Repository Importing**
44
-
even after import completes. This means that the commit did not trigger
45
-
autoclose because the repository was importing at the time it was processed,
46
-
not necessarily that the repository is still importing.
47
-
48
-
- **Yes** At the time the commit was imported, autoclose triggered and
49
-
Phabricator attempted to close related objects.
50
-
- **No, Repository Importing** At the time the commit was processed, the
51
-
repository was still importing. Autoclose does not activate until a
52
-
repository fully imports for the first time.
53
-
- **No, Autoclose Disabled** At the time the commit was processed, the
54
-
repository had autoclose disabled.
55
-
- **No, Not On Autoclose Branch** At the time the commit was processed,
56
-
no containing branch was configured to autoclose.
57
-
- //Field Not Present// This commit was processed before we implemented
58
-
this diagnostic feature, and no information is available.
59
-
60
-
61
-
Manually Closing Revisions
62
-
==========================
63
-
64
-
If autoclose didn't activate for some reason and you want to manually close
65
-
revisions, you can do so in several ways:
66
-
67
-
**Close Revision**: The revision author can use the "Close Revision" action
68
-
from the web UI, located in the action dropdown on the revision page (where
69
-
reviewers would "Accept Revision" or "Request Changes").
70
-
71
-
`differential.always-allow-close`: If you set this option in {nav Config},
72
-
any user can take the "Close Revision" action in the web UI.
73
-
74
-
`arc close-revision`: You can close revisions from the command line by using
75
-
`arc close-revision`.
76
-
77
-
78
-
Next Steps
79
-
==========
80
-
81
-
Continue by:
82
-
83
-
- troubleshooting in greater depth with
84
-
@{article:Troubleshooting Repository Imports}.
+47
-22
src/docs/user/userguide/diffusion_managing.diviner
+47
-22
src/docs/user/userguide/diffusion_managing.diviner
···
137
137
observing.
138
138
139
139
140
+
Basics: Disable Publishing
141
+
==========================
142
+
143
+
You can disable publishing for a repository. For more details on what this
144
+
means, see @{article:Diffusion User Guide: Permanent Refs}.
145
+
146
+
This is primarily useful if you need to perform major maintenance on a
147
+
repository (like rewriting a large part of the repository history) and you
148
+
don't want the maintenance to generate a large volume of email and
149
+
notifications. You can disable publishing, apply major changes, wait for the
150
+
new changes to import, and then reactivate publishing.
151
+
152
+
140
153
Basics: Deactivate Repository
141
154
=============================
142
155
···
287
300
This panel is not available for Subversion repositories, because Subversion
288
301
does not have formal branches.
289
302
290
-
You can configure **Default Branch**. This controls which branch is shown by
303
+
You can configure a **Default Branch**. This controls which branch is shown by
291
304
default in the UI. If no branch is provided, Phabricator will use `master` in
292
305
Git and `default` in Mercurial.
293
306
294
-
If you want Diffusion to ignore some branches in the repository, you can
295
-
configure **Track Only**. Other branches will be ignored. If you do not specify
296
-
any branches, all branches are tracked.
307
+
**Fetch Refs**: In Git, if you are observing a remote repository, you can
308
+
specify that you only want to fetch a subset of refs using "Fetch Refs".
297
309
298
-
When specifying branches, you should enter one branch name per line. You can
299
-
use regular expressions to match branches by wrapping an expression in
300
-
`regexp(...)`. For example:
310
+
Normally, all refs (`refs/*`) are fetched. This means all branches, all tags,
311
+
and all other refs.
301
312
302
-
| Example | Effect |
303
-
|---------|--------|
304
-
| `master` | Track only `master`.
305
-
| `regexp(/^release-/)` | Track all branches which start with `release-`.
306
-
| `regexp(/^(?!temp-)/)` | Do not track branches which start with `temp-`.
313
+
If you want to fetch only a few specific branches, you can list only those
314
+
branches. For example, this will fetch only the branch "master":
307
315
316
+
```
317
+
refs/heads/master
318
+
```
308
319
309
-
Actions
310
-
======
320
+
You can fetch all branches and tags (but ignore other refs) like this:
311
321
312
-
The **Actions** panel can configure notifications and publishing behavior.
322
+
```
323
+
refs/heads/*
324
+
refs/tags/*
325
+
```
313
326
314
-
Normally, Phabricator publishes notifications when it discovers new commits.
315
-
You can disable publishing for a repository by turning off **Publish/Notify**.
316
-
This will disable notifications, feed, and Herald (including audits and build
317
-
plans) for this repository.
327
+
This may be useful if the remote is on a service like GitHub, GitLab, or
328
+
Gerrit and uses custom refs (like `refs/pull/` or `refs/changes/`) to store
329
+
metadata that you don't want to bring into Phabricator.
330
+
331
+
**Permanent Refs**: To learn more about permanent refs, see:
318
332
319
-
When Phabricator discovers a new commit, it can automatically close associated
320
-
revisions and tasks. If you don't want Phabricator to close objects when it
321
-
discovers new commits, disable **Autoclose** for the repository.
333
+
- @{article:Diffusion User Guide: Permanent Refs}
334
+
335
+
By default, Phabricator considers all branches to be permanent refs. If you
336
+
only want some branches to be treated as permanent refs, specify them here.
337
+
338
+
When specifying branches, you should enter one branch name per line. You can
339
+
use regular expressions to match branches by wrapping an expression in
340
+
`regexp(...)`. For example:
341
+
342
+
| Example | Effect |
343
+
|---------|--------|
344
+
| `master` | Only the `master` branch is a permanent ref.
345
+
| `regexp(/^release-/)` | Branches are permanent if they start with `release-`.
346
+
| `regexp(/^(?!temp-)/)` | Branches named `temp-` are not permanent.
322
347
323
348
324
349
Staging Area
+81
src/docs/user/userguide/diffusion_permanent.diviner
+81
src/docs/user/userguide/diffusion_permanent.diviner
···
1
+
@title Diffusion User Guide: Permanent Refs
2
+
@group userguide
3
+
4
+
Explains when Diffusion will take actions in response to discovering commits.
5
+
6
+
Overview
7
+
========
8
+
9
+
Diffusion can close tasks and revisions and take other actions when commits
10
+
appear in a repository (either because they were pushed to Phabricator, or
11
+
because they were pushed to some remote which Phabricator is observing).
12
+
13
+
This document explains when Diffusion acts on commits and how to configure this
14
+
behavior.
15
+
16
+
17
+
Publishing Commits
18
+
==================
19
+
20
+
Diffusion distinguishes between "pushed" and "published" commits.
21
+
22
+
Not all commits that are pushed to a repository are destined for greatness:
23
+
for example, many tools push temporary commits to secret places like
24
+
`refs/pull/123`, `refs/notes/*`, or `refs/changes/12/345678/1`.
25
+
26
+
Sometimes, human users intentionally push changes to branches like
27
+
"tmp-hack-ignore-123". This is formally discouraged by Phabricator, but the
28
+
practice is so widespread that we've given up trying to stop anyone from doing
29
+
it.
30
+
31
+
Phabricator will import these commits and create pages for them so you can view
32
+
them in the web UI and link to them, but does not take any other actions until
33
+
they are "published".
34
+
35
+
A commit is "published" when it becomes reachable from a permanent ref. By
36
+
default, all branches are permanent refs, so pushing a commit to "master" will
37
+
publish it, but pushing a commit to `refs/pull/123` (either directly, or by
38
+
using a tool like GitHub) will not.
39
+
40
+
Usually, commits are published by pushing them directly to a permanent branch
41
+
like "master", or by merging a temporary branch into a permanent branch.
42
+
43
+
When a commit is published, Phabricator acts on it and:
44
+
45
+
- sends email;
46
+
- delivers notifications;
47
+
- publishes a feed story;
48
+
- triggers Audits;
49
+
- runs Herald rules;
50
+
- updates mentioned objects;
51
+
- closes referenced tasks; and
52
+
- closes associated revisions.
53
+
54
+
55
+
Configuring Repositories
56
+
========================
57
+
58
+
You can control publishing behavior in two primary ways: by configuring
59
+
which refs are considered to be permanent refs, and by disabling publishing
60
+
entirely.
61
+
62
+
By default, all branches are considered permanent refs and all other refs
63
+
(including tags and other arbitrary custom refs) are considered nonpermanent.
64
+
This means that, by default, pushing commits to a branch like
65
+
"tmp-hack-ignore-123" will publish those commits.
66
+
67
+
If you want to be free to push commits to temporary branches like this and
68
+
only want commits on certain branches (like "master") to be published,
69
+
configure which refs are treated as permanent by editing
70
+
{nav Branches > Permanent Refs} from the "Manage" page of the repository.
71
+
72
+
To disable publishing entirely, select {nav Basics > Disable Publishing}.
73
+
74
+
75
+
Next Steps
76
+
==========
77
+
78
+
Continue by:
79
+
80
+
- troubleshooting in greater depth with
81
+
@{article:Troubleshooting Repository Imports}.