@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 Owners docs a bit
Summary:
Fixes T9218. Fixes T8320. Fixes T8661. This isn't exhaustive but documents the stuff that cropped up in this iteration as needing documentation. In particular:
- Be explicit about multiple ownership.
- Explain value of having one place to update your giant regexp of a trillion paths.
Test Plan: Read documentation.
Reviewers: chad
Reviewed By: chad
Maniphest Tasks: T8320, T8661, T9218
Differential Revision: https://secure.phabricator.com/D14023
+61
-21
+1
-1
src/applications/owners/application/PhabricatorOwnersApplication.php
+1
-1
src/applications/owners/application/PhabricatorOwnersApplication.php
+60
-20
src/docs/user/userguide/owners.diviner
+60
-20
src/docs/user/userguide/owners.diviner
···
1
-
@title Owners Tool User Guide
1
+
@title Owners User Guide
2
2
@group userguide
3
3
4
-
Use Owners to define and/or monitor code you care about.
4
+
Group files in a codebase into packages and define ownership.
5
5
6
-
= Packages =
6
+
Overview
7
+
========
7
8
8
-
Owners tool allows you to define a code package by specifying a group of paths.
9
-
The package can then be used to monitor the paths. For example, it can be used
10
-
in Herald rules and in the "Related Commits" feature (see below).
9
+
The Owners application allows you to group files in a codebase (or across
10
+
codebases) into packages. This can make it easier to reference a module or
11
+
subsystem in other applications, like Herald.
11
12
12
-
= Related Commits =
13
13
14
-
Once the package is defined, all future commits touching any path defined in
15
-
the package will be recorded as "Related Commits" of the package.
14
+
Creating a Package
15
+
==================
16
16
17
-
= Commits Needing Attention =
17
+
To create a package, choose a name and add some files which belong to the
18
+
package. For example, you might define an "iOS Application" package by
19
+
including these paths:
18
20
19
-
Owners tool enables the owners of the package to monitor the commits that might
20
-
need attention. If "auditing" is enabled for a package, a related commit will
21
-
be marked as "Needing Attention" if
21
+
/conf/ios/
22
+
/src/ios/
23
+
/shared/assets/mobile/
22
24
23
-
- it's neither authored nor reviewed by an owner of the package,
24
-
- no revision found for the commit,
25
-
- the commit author is not recognized, or
26
-
- the author or the reviewer specified in the commits don't match the ones in
27
-
the Differential revision
25
+
Any files in those directories are considered to be part of the package, and
26
+
you can now conveniently refer to them (for example, in a Herald rule) by
27
+
refering to the package instead of copy/pasting a huge regular expression
28
+
into a bunch of places.
28
29
29
-
The owners of the package can accept or specify concern for such commits by
30
-
clicking the "Audit Status" link.
30
+
If new source files are later added, or the scope of the package otherwise
31
+
expands or contracts, you can edit the package definition to keep things
32
+
updated.
33
+
34
+
You can use "exclude" paths to ignore subdirectories which would otherwise
35
+
be considered part of the package. For example, you might exclude a path
36
+
like this:
37
+
38
+
/conf/ios/generated/
39
+
40
+
Perhaps that directory contains some generated configuration which frequently
41
+
changes, and which you aren't concerned about.
42
+
43
+
After creating a package, files the package contains will be identified as
44
+
belonging to the package when you look at them in Diffusion, or look at changes
45
+
which affect them in Diffusion or Differential.
46
+
47
+
48
+
Files in Multiple Packages
49
+
==========================
50
+
51
+
Multiple packages may own the same file. For example, both the
52
+
"Android Application" and the "iOS Application" packages might own a path
53
+
like this, containing resources used by both:
54
+
55
+
/shared/assets/mobile/
56
+
57
+
If both packages own this directory, files in the directory are considered to
58
+
be part of both packages.
59
+
60
+
Packages do not need to have claims of equal specificity to own files. For
61
+
example, if you have a "Design Assets" package which owns this path:
62
+
63
+
/shared/assets/
64
+
65
+
...it will //also// own all of the files in the `mobile/` subdirectory. In this
66
+
configuration, these files are part of three packages: "iOS Application",
67
+
"Android Application", and "Design Assets".
68
+
69
+
(You can use an "exclude" rule if you want to make a different package with a
70
+
more specific claim the owner of a file or subdirectory.)