@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
Document most of the new Diffusion management panel
Summary: Ref T10923. This isn't complete yet, but reduces lies and increases truths.
Test Plan: Read documentation, clicked new "Documentation" nav item.
Reviewers: chad
Reviewed By: chad
Maniphest Tasks: T10923
Differential Revision: https://secure.phabricator.com/D15868
+382
-67
+2
src/__phutil_library_map__.php
+2
src/__phutil_library_map__.php
···
754
754
'DiffusionRepositoryController' => 'applications/diffusion/controller/DiffusionRepositoryController.php',
755
755
'DiffusionRepositoryDatasource' => 'applications/diffusion/typeahead/DiffusionRepositoryDatasource.php',
756
756
'DiffusionRepositoryDefaultController' => 'applications/diffusion/controller/DiffusionRepositoryDefaultController.php',
757
+
'DiffusionRepositoryDocumentationManagementPanel' => 'applications/diffusion/management/DiffusionRepositoryDocumentationManagementPanel.php',
757
758
'DiffusionRepositoryEditActivateController' => 'applications/diffusion/controller/DiffusionRepositoryEditActivateController.php',
758
759
'DiffusionRepositoryEditConduitAPIMethod' => 'applications/diffusion/conduit/DiffusionRepositoryEditConduitAPIMethod.php',
759
760
'DiffusionRepositoryEditController' => 'applications/diffusion/controller/DiffusionRepositoryEditController.php',
···
4973
4974
'DiffusionRepositoryController' => 'DiffusionController',
4974
4975
'DiffusionRepositoryDatasource' => 'PhabricatorTypeaheadDatasource',
4975
4976
'DiffusionRepositoryDefaultController' => 'DiffusionController',
4977
+
'DiffusionRepositoryDocumentationManagementPanel' => 'DiffusionRepositoryManagementPanel',
4976
4978
'DiffusionRepositoryEditActivateController' => 'DiffusionRepositoryEditController',
4977
4979
'DiffusionRepositoryEditConduitAPIMethod' => 'PhabricatorEditEngineAPIMethod',
4978
4980
'DiffusionRepositoryEditController' => 'DiffusionController',
+1
-1
src/applications/diffusion/controller/DiffusionRepositoryManageController.php
+1
-1
src/applications/diffusion/controller/DiffusionRepositoryManageController.php
···
109
109
$key = $panel->getManagementPanelKey();
110
110
$label = $panel->getManagementPanelLabel();
111
111
$icon = $panel->getManagementPanelIcon();
112
-
$href = $repository->getPathURI("manage/{$key}/");
112
+
$href = $panel->getPanelNavigationURI();
113
113
114
114
$item = id(new PHUIListItemView())
115
115
->setKey($key)
+29
src/applications/diffusion/management/DiffusionRepositoryDocumentationManagementPanel.php
+29
src/applications/diffusion/management/DiffusionRepositoryDocumentationManagementPanel.php
···
1
+
<?php
2
+
3
+
final class DiffusionRepositoryDocumentationManagementPanel
4
+
extends DiffusionRepositoryManagementPanel {
5
+
6
+
const PANELKEY = 'documentation';
7
+
8
+
public function getManagementPanelLabel() {
9
+
return pht('Documentation');
10
+
}
11
+
12
+
public function getManagementPanelOrder() {
13
+
return 3000;
14
+
}
15
+
16
+
public function getManagementPanelIcon() {
17
+
return 'fa-book bluegrey';
18
+
}
19
+
20
+
public function buildManagementPanelContent() {
21
+
return null;
22
+
}
23
+
24
+
public function getPanelNavigationURI() {
25
+
return PhabricatorEnv::getDoclink(
26
+
'Diffusion User Guide: Managing Repositories');
27
+
}
28
+
29
+
}
+3
src/applications/diffusion/management/DiffusionRepositoryManagementPanel.php
+3
src/applications/diffusion/management/DiffusionRepositoryManagementPanel.php
+1
-1
src/applications/diffusion/management/DiffusionRepositoryURIsManagementPanel.php
+1
-1
src/applications/diffusion/management/DiffusionRepositoryURIsManagementPanel.php
+34
-60
src/docs/user/userguide/diffusion.diviner
+34
-60
src/docs/user/userguide/diffusion.diviner
···
1
1
@title Diffusion User Guide
2
2
@group userguide
3
3
4
-
Guide to Diffusion, the Phabricator repository browser.
4
+
Guide to Diffusion, the Phabricator application for hosting and browsing
5
+
repositories.
5
6
6
-
= Overview =
7
+
Overview
8
+
========
7
9
8
-
Diffusion is a repository browser which allows you to explore source code in a
9
-
Subversion, Git, or Mercurial repository. It is somewhat similar to software
10
-
like Trac and GitWeb.
10
+
Diffusion allows you to create repositories so that you can browse them from
11
+
the web and interact with them from other applications.
11
12
12
-
Diffusion can either import a read-only copy of repositories hosted somewhere
13
-
else (for example, from GitHub, Bitbucket or existing hosting) or host
14
-
repositories within Phabricator. Hosted repositories support a variety of
15
-
triggers and access controls.
13
+
Diffusion can host repositories locally, or observe existing remote
14
+
repositories which are hosted elsewhere (for example, on GitHub, Bitbucket, or
15
+
other existing hosting). Both types of repositories can be browsed and
16
+
interacted with, but hosted repositories support some additional triggers
17
+
and access controls which are not available for observed repositories.
16
18
17
19
Diffusion is integrated with the other tools in the Phabricator suite. For
18
20
instance:
···
24
26
- for hosted repositories, Herald can enforce granular access control rules;
25
27
- in all the tools, commit names are automatically linked.
26
28
27
-
= Adding Repositories =
29
+
The remainder of this document walks through creating, configuring, and
30
+
managing repositories.
31
+
32
+
33
+
Adding Repositories
34
+
===================
28
35
29
36
Repository administration is accomplished through Diffusion. You can use the
30
-
web interface in Diffusion to import an external repository, or create a new
37
+
web interface in Diffusion to observe an external repository or create a new
31
38
hosted repository.
32
39
33
40
- For hosted repositories, make sure you go through the setup instructions
···
35
42
- For all repositories, you'll need to be running the daemons. If you have
36
43
not set them up yet, see @{article:Managing Daemons with phd}.
37
44
38
-
By default, you must be an administrator to create a new repository.
39
-
40
-
= Repository Callsigns and Commit Names =
41
-
42
-
Each repository is identified by a "callsign", which is a short uppercase string
43
-
like "P" (for Phabricator) or "ARC" (for Arcanist).
44
-
45
-
Each repository must have a unique callsign. Callsigns must be unique within
46
-
an install but do not need to be globally unique, so you are free to use the
47
-
single-letter callsigns for brevity. For example, Facebook uses "E" for the
48
-
Engineering repository, "O" for the Ops repository, "Y" for a Yum package
49
-
repository, and so on, while Phabricator uses "P", "ARC", "PHU" for libphutil,
50
-
and "J" for Javelin. Keeping callsigns brief will make them easier to use, and
51
-
the use of one-character callsigns is recommended if they are reasonably
52
-
evocative and you have no more than 26 tracked repositories.
53
-
54
-
The primary goal of callsigns is to namespace commits to SVN repositories: if
55
-
you use multiple SVN repositories, each repository has a revision 1, revision 2,
56
-
etc., so referring to them by number alone is ambiguous. However, even for Git
57
-
they impart additional information to human readers and allow parsers to detect
58
-
that something is a commit name with high probability (and allow distinguishing
59
-
between multiple copies of a repository).
45
+
By default, you must be an administrator to create a new repository. You can
46
+
change this in the application settings.
60
47
61
-
Diffusion uses this callsign and information about the commit itself to generate
62
-
a commit name, like "rE12345" or "rP28146171ce1278f2375e3646a1e1ea3fd56fc5a3".
63
-
The "r" stands for "revision". It is followed by the repository callsign, and
64
-
then a VCS-specific commit identifier (for SVN, the commit number; for Git and
65
-
Mercurial, the commit hash). When writing the name of a Git commit you may
66
-
abbreviate the hash, but note that hash collisions are probable for short prefix
67
-
lengths. See this post on the LKML for a historical explanation of Git's
68
-
occasional internal use of 7-character hashes:
69
48
70
-
https://lkml.org/lkml/2010/10/28/287
49
+
Managing Repositories
50
+
=====================
71
51
72
-
Because 7-character hashes are likely to collide for even moderately large
73
-
repositories, Diffusion generally uses either a 16-character prefix (which makes
74
-
collisions very unlikely) or the full 40-character hash (which makes collisions
75
-
astronomically unlikely).
52
+
Diffusion repositories have an array of configurable options and behaviors. For
53
+
details on the available options and guidance on managing and administrating
54
+
repositories, see @{article:Diffusion User Guilde: Managing Repositories}.
76
55
77
-
= Running Diffusion Daemons =
78
56
79
-
In most cases, it is sufficient to run:
57
+
Repository Clustering
58
+
=====================
80
59
81
-
phabricator/bin/ $ ./phd start
60
+
Phabricator repository hosts can be set up in a cluster configuration so you
61
+
can lose hosts with minimal downtime and data loss. This is an advanced feature
62
+
which most installs do not need to pursue.
82
63
83
-
...to start the daemons. For a more in-depth explanation of `phd` and daemons,
84
-
see @{article:Managing Daemons with phd}.
64
+
To get started with clustering, see @{article:Clustering Introduction}. For
65
+
details on repository clustering, see @{article:Cluster: Repositories}.
85
66
86
-
NOTE: If you have an unusually large install with multiple web frontends, see
87
-
notes in @{article:Managing Daemons with phd}.
88
67
89
-
You can use the repository detail screen and the Daemon Console to monitor the
90
-
daemons and their progress importing the repository. Small repositories should
91
-
import quickly, while larger repositories may take some time. Commits should
92
-
begin appearing in Diffusion within a few minutes for all but the largest
93
-
repositories.
94
-
95
-
= Next Steps =
68
+
Next Steps
69
+
==========
96
70
97
71
Continue by:
98
72
+310
src/docs/user/userguide/diffusion_managing.diviner
+310
src/docs/user/userguide/diffusion_managing.diviner
···
1
+
@title Diffusion User Guide: Managing Repositories
2
+
@group userguide
3
+
4
+
Guide to configuring and managing repositories in Diffusion.
5
+
6
+
Overview
7
+
========
8
+
9
+
After you create a new repository in Diffusion or select **Manage Repository**
10
+
from the main screen if an existing repository, you'll be taken to the
11
+
repository management interface for that repository.
12
+
13
+
On this interface, you'll find many options which allow you to configure the
14
+
behavior of a repository. This document walks through the options.
15
+
16
+
Basics
17
+
======
18
+
19
+
The **Basics** section of the management interface allows you to configure
20
+
the repository name, description, and identifiers. You can also activate or
21
+
deactivate the repository here, and configure a few other miscellaneous
22
+
settings.
23
+
24
+
Basics: Name
25
+
============
26
+
27
+
The repository name is a human-readable primary name for the repository. It
28
+
does not need to be unique
29
+
30
+
Because the name is not unique and does not have any meaningful restrictions,
31
+
it's fairly ambiguous and isn't very useful as an identifier. The other basic
32
+
information (primarily callsigns and short names) gives you control over
33
+
repository identifiers.
34
+
35
+
36
+
Basics: Callsigns
37
+
=================
38
+
39
+
Each repository can optionally be identified by a "callsign", which is a short
40
+
uppercase string like "P" (for Phabricator) or "ARC" (for Arcanist).
41
+
42
+
The primary goal of callsigns is to namespace commits to SVN repositories: if
43
+
you use multiple SVN repositories, each repository has a revision 1, revision 2,
44
+
etc., so referring to them by number alone is ambiguous.
45
+
46
+
However, even for Git and Mercurial they impart additional information to human
47
+
readers and allow parsers to detect that something is a commit name with high
48
+
probability (and allow distinguishing between multiple copies of a repository).
49
+
50
+
Configuring a callsign can make interacting with a commonly-used repository
51
+
easier, but you may not want to bother assigning one to every repository if you
52
+
have some similar, templated, or rarely-used repositories.
53
+
54
+
If you choose to assign a callsign to a repository, it must be unique within an
55
+
install but do not need to be globally unique, so you are free to use the
56
+
single-letter callsigns for brevity. For example, Facebook uses "E" for the
57
+
Engineering repository, "O" for the Ops repository, "Y" for a Yum package
58
+
repository, and so on, while Phabricator uses "P", "ARC", "PHU" for libphutil,
59
+
and "J" for Javelin. Keeping callsigns brief will make them easier to use, and
60
+
the use of one-character callsigns is encouraged if they are reasonably
61
+
evocative.
62
+
63
+
If you configure a callsign like `XYZ`, Phabricator will activate callsign URIs
64
+
and activate the callsign identifier (like `rXYZ`) for the repository. These
65
+
more human-readable identifiers can make things a little easier to interact
66
+
with.
67
+
68
+
69
+
Basics: Short Name
70
+
==================
71
+
72
+
Each repository can optionally have a unique short name. Short names must be
73
+
unique and have some minor restrictions to make sure they are unambiguous and
74
+
appropriate for use as directory names and in URIs.
75
+
76
+
77
+
Basics: Description
78
+
===================
79
+
80
+
You may optionally provide a brief (or, at your discretion, excruciatingly
81
+
long) human-readable description of the repository. This description will be
82
+
shown on the main repository page.
83
+
84
+
You can also create a `README` file at the repository root (or in any
85
+
subdirectory) to provide information about the repository. These formats are
86
+
supported:
87
+
88
+
| File Name | Rendered As...
89
+
|-------------------|---------------
90
+
| `README` | Plain Text
91
+
| `README.txt` | Plain Text
92
+
| `README.remarkup` | Remarkup
93
+
| `README.md` | Remarkup
94
+
| `README.rainbow` | Rainbow
95
+
96
+
97
+
Basics: Encoding
98
+
================
99
+
100
+
Before content from the repository can be shown in the web UI or embedded in
101
+
other contexts like email, it must be converted to UTF-8.
102
+
103
+
Most source code is written in UTF-8 or a subset of UTF-8 (like plain ASCII)
104
+
already, so everything will work fine. The majority of repositories do not need
105
+
to adjust this setting.
106
+
107
+
If your repository is primarily written in some other encoding, specify it here
108
+
so Phabricator can convert from it properly when reading content to embed in
109
+
a webpage or email.
110
+
111
+
112
+
Basics: Dangerous Changes
113
+
=========================
114
+
115
+
By default, repositories are protected against dangerous changes. Dangerous
116
+
changes are operations which rewrite or destroy repository history (for
117
+
example, by deleting or rewriting branches). Normally, these take the form
118
+
of `git push --force` or similar.
119
+
120
+
It is normally a good idea to leave this protection enabled because most
121
+
scalable workflows rarely rewrite repository history and it's easy to make
122
+
mistakes which are expensive to correct if this protection is disabled.
123
+
124
+
If you do occasionally need to rewite published history, you can treat this
125
+
option like a safety: disable it, perform required rewrites, then enable it
126
+
again.
127
+
128
+
If you fully disable this at the repository level, you can still use Herald to
129
+
selectively protect certain branches or grant this power to a limited set of
130
+
users.
131
+
132
+
This option is only available in Git and Mercurial, because it is impossible
133
+
to make dangerous changes in Subversion.
134
+
135
+
This option has no effect if a repository is not hosted because Phabricator
136
+
can not prevent dangerous changes in a remote repository it is merely
137
+
observing.
138
+
139
+
140
+
Basics: Deactivate Repository
141
+
=============================
142
+
143
+
Repositories can be deactivated. Deactivating a repository has these effects:
144
+
145
+
- the repository will no longer be updated;
146
+
- users will no longer be able to clone/fetch/checkout the repository;
147
+
- users will no longer be able to push to the repository; and
148
+
- the repository will be hidden from view in default queries.
149
+
150
+
When repositories are created for the first time, they are deactivated. This
151
+
gives you an opportuinty to customize settings, like adjusting policies or
152
+
configuring a URI to observe. You must activate a repository before it will
153
+
start working normally.
154
+
155
+
156
+
Basics: Delete Repository
157
+
=========================
158
+
159
+
Repositories can not be deleted from the web UI, so this option is always
160
+
disabled. Clicking it gives you information about how to delete a repository.
161
+
162
+
Repositories can only be deleted from the command line, with `bin/remove`:
163
+
164
+
```
165
+
$ ./bin/remove destroy <repository>
166
+
```
167
+
168
+
WARNING: This command will issue you a dire warning about the severity of the
169
+
action you are taking. Heed this warning. You are **strongly discouraged** from
170
+
destroying repositories. Instead, deactivate them.
171
+
172
+
173
+
Policies
174
+
========
175
+
176
+
The **Policies** section of the management interface allows you to review and
177
+
manage repository access policies.
178
+
179
+
You can configure granular access policies for each repository to control who
180
+
can view, clone, administate, and push to the repository.
181
+
182
+
183
+
Policies: View
184
+
==============
185
+
186
+
The view policy for a repository controls who can view the repository from
187
+
the web UI and clone, fetch, or check it out from Phabricator.
188
+
189
+
Users who can view a repository can also access the "Manage" interface to
190
+
review information about the repository and examine the edit history, but can
191
+
not make any changes.
192
+
193
+
194
+
Policies: Edit
195
+
==============
196
+
197
+
The edit policy for a repository controls who can change repository settings
198
+
using the "Manage" interface. In essence, this is permission to administrate
199
+
the repository.
200
+
201
+
You must be able to view a repository to edit it.
202
+
203
+
You do not need this permission to push changes to a repository.
204
+
205
+
206
+
Policies: Push
207
+
==============
208
+
209
+
The push policy for a repository controls who can push changes to the
210
+
repository.
211
+
212
+
This policy has no effect if Phabricator is not hosting the repository, because
213
+
it can not control who is allowed to make changes to a remote repository it is
214
+
merely observing.
215
+
216
+
You must also be able to view a repository to push to it.
217
+
218
+
You do not need to be able to edit a repository to push to it.
219
+
220
+
Further restrictions on who can push (and what they can push) can be configured
221
+
for hosted repositories with Herald, which allows you to write more
222
+
sophisticated rules that evaluate when Phabricator receives a push. To get
223
+
started with Herald, see @{article:Herald User Guide}.
224
+
225
+
Additionally, Git and Mercurial repositories have a setting which allows
226
+
you to **Prevent Dangerous Changes**. This setting is enabled by default and
227
+
will prevent any users from pushing changes which rewrite or destroy history.
228
+
229
+
230
+
URIs
231
+
====
232
+
233
+
The **URIs** panel allows you to add and manage URIs which Phabricator will
234
+
fetch from, serve from, and push to.
235
+
236
+
These options are covered in detail in @{article:Diffusion User Guide: URIs}.
237
+
238
+
239
+
Repository Identifiers and Names
240
+
================================
241
+
242
+
Repositories have several short identifiers which you can use to refer to the
243
+
repository. For example, if you use command-line administrative tools to
244
+
interact with a repository, you'll provide one of these identifiers:
245
+
246
+
```
247
+
$ ./bin/repository update <identifier>
248
+
```
249
+
250
+
The identifiers available for a repository depend on which options are
251
+
configured. Each repository may have several identifiers:
252
+
253
+
- An **ID** identifier, like `R123`. This is available for all repositories.
254
+
- A **callsign** identifier, like `rXY`. This is available for repositories
255
+
with a callsign.
256
+
- A **short name** identifier, like `xylophone`. This is available for
257
+
repositories with a short name.
258
+
259
+
All three identifiers can be used to refer to the repository in cases where
260
+
the intent is unambiguous, but only the first two forms work in ambiguous
261
+
contexts.
262
+
263
+
For example, if you type `R123` or `rXY` into a comment, Phabricator will
264
+
recognize them as references to the repository. If you type `xylophone`, it
265
+
assumes you mean the word "xylophone".
266
+
267
+
Only the `R123` identifier is immutable: the others can be changed later by
268
+
adjusting the callsign or short name for the repository.
269
+
270
+
271
+
Commit Identifiers
272
+
==================
273
+
274
+
Diffusion uses repository identifiers and information about the commit itself
275
+
to generate globally unique identifers for each commit, like `rE12345`.
276
+
277
+
Each commit may have several identifiers:
278
+
279
+
- A repository **ID** identifier, like `R123:abcdef123...`.
280
+
- A repository **callsign** identifier, like `rXYZabcdef123...`. This only
281
+
works if a repository has a callsign.
282
+
- Any unique prefix of the commit hash.
283
+
284
+
Git and Mercurial use commit hashes to identify commits, and Phabricator will
285
+
recognize a commit if the hash prefix is unique and sufficiently long. Commit
286
+
hashes qualified with a repository identifier must be at least 5 characters
287
+
long; unqualified commit hashes must be at least 7 characters long.
288
+
289
+
In Subversion, commit identifiers are sequential integers and prefixes can not
290
+
be used to identify them.
291
+
292
+
When rendering the name of a Git or Mercurial commit hash, Phabricator tends to
293
+
shorten it to 12 characters. This "short length" is relatively long compared to
294
+
Git itself (which often uses 7 characters). See this post on the LKML for a
295
+
historical explanation of Git's occasional internal use of 7-character hashes:
296
+
297
+
https://lkml.org/lkml/2010/10/28/287
298
+
299
+
Because 7-character hashes are likely to collide for even moderately large
300
+
repositories, Diffusion generally uses either a 12-character prefix (which makes
301
+
collisions very unlikely) or the full 40-character hash (which makes collisions
302
+
astronomically unlikely).
303
+
304
+
305
+
Next Steps
306
+
==========
307
+
308
+
Continue by:
309
+
310
+
- returning to the @{article:Diffusion User Guide}.
+2
-2
src/docs/user/userguide/diffusion_updates.diviner
+2
-2
src/docs/user/userguide/diffusion_updates.diviner
···
89
89
- If your repository is hosted on Phabricator, this will also be done for you
90
90
automatically.
91
91
- You can schedule an update from the web interface, in Diffusion >
92
-
(Choose a Repository) > Edit Repository > Update Now.
92
+
(Choose a Repository) > Manage Repository > Status > Update Now.
93
93
- You can make a call to the Conduit API method `diffusion.looksoon`. This
94
94
hints to Phabricator that it should poll a repository as soon as it can.
95
95
All of the other mechanisms do this under the hood.
···
109
109
You can manually run a repository update from the command line to troubleshoot
110
110
issues, using the `--trace` flag to get full details:
111
111
112
-
phabricator/ $ ./bin/repository update --trace <callsign>
112
+
phabricator/ $ ./bin/repository update --trace <repository>
113
113
114
114
To catch potential issues with permissions, run this command as the same user
115
115
that the daemons run as.
-3
src/docs/user/userguide/diffusion_uris.diviner
-3
src/docs/user/userguide/diffusion_uris.diviner