@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 Herald documentation for modern policies and beahvior
Summary: Ref T11428. This documentation was a bit misleading and out of date. Update it to reflect modern reality.
Test Plan: Read documentation.
Reviewers: chad
Reviewed By: chad
Maniphest Tasks: T11428
Differential Revision: https://secure.phabricator.com/D16384
+116
-74
+116
-74
src/docs/user/userguide/herald.diviner
+116
-74
src/docs/user/userguide/herald.diviner
···
3
3
4
4
Use Herald to get notified of changes you care about.
5
5
6
-
= Overview =
6
+
Overview
7
+
========
7
8
8
-
Herald allows you to write processing rules that take effect when objects (such
9
-
as Differential revisions and commits) are created or updated. For instance, you
10
-
might want to get notified every time someone sends out a revision that affects
11
-
some file you're interested in, even if they didn't add you as a reviewer.
9
+
Herald allows you to write rules which run automatically when objects (like
10
+
tasks or commits) are created or updated. For instance, you might want to get
11
+
notified every time someone sends out a revision that affects some file you're
12
+
interested in, even if they didn't add you as a reviewer.
12
13
13
-
Herald is less useful for small organizations (where everyone will generally
14
-
know most of what's going on) but the usefulness of the application increases
15
-
as an organization scales. Once there is too much activity to keep track of it
16
-
all, Herald allows you to filter it down so you're only notified of things you
17
-
are interested in.
14
+
One way to think about Herald is that it is a lot like the mail rules you can
15
+
set up in most email clients to organize mail based on "To", "Subject", etc.
16
+
Herald works very similarly, but operates on Phabricator objects (like revisions
17
+
and commits) instead of emails.
18
18
19
-
= Global and Personal Rules =
19
+
For example, you can write a personal rule like this which triggers on tasks:
20
20
21
-
You can create two kinds of Herald rules, //global// and //personal//:
21
+
> When [ all of ] these conditions are met:
22
+
> [ Title ][ contains ][ quasar ]
23
+
> Take these actions [ every time ] this rule matches:
24
+
> [ Add me as a subscriber ]
22
25
23
-
- **Personal Rules** are rules you own, but they can only affect you. Only
24
-
you can edit or delete personal rules, but their actions are limited to
25
-
adding you to CC, subscribing you, etc.
26
-
- **Global Rules** are rules everyone owns, and they can affect anything.
27
-
Anyone can edit or delete a global rule, and they can take any action,
28
-
including affecting projects and mailing lists.
26
+
This rule will automatically subscribe you to any newly created or updated
27
+
tasks that contain "quasar" in the title.
29
28
30
-
The general idea is to prevent individuals from controlling rules that affect
31
-
shared resources, so if a rule needs to be updated it's not a big deal if the
32
-
person who created it is on vacation.
29
+
Herald rules are often used to: notify users, add reviewers, initiate audits,
30
+
classify objects, block commits, enforce CLAs, and run builds.
33
31
34
-
= Rules, Conditions and Actions =
35
32
36
-
The best way to think of Herald is as a system similar to the mail rules you can
37
-
set up in most email clients, to organize mail based on "To", "Subject", etc.
38
-
Herald works very similarly, but operates on Phabricator objects (like revisions
39
-
and commits) instead of emails.
33
+
Working with Rules
34
+
==================
40
35
41
-
Every time an object is created or updated, Herald rules are run on it and
42
-
the actions for any matching rules are taken.
36
+
To create new Herald rules, navigate to the {nav Herald} application and select
37
+
{nav Create Herald Rule}.
43
38
44
-
To create a new Herald rule, choose which type of event you want to act on
45
-
(e.g., changes to Differential Revisions, or Commits), and then set a list of
46
-
conditions. For example, you might add the condition `Author is alincoln
47
-
(Abraham Lincoln)` to keep track of everything alincoln does. Finally, set
48
-
a list of actions to take when the conditions match, like adding yourself to the
49
-
CC list.
39
+
Next, you'll choose an event that you want to write a rule for: for example,
40
+
a rule for when commits are discovered or a rule for when tasks are created or
41
+
updated.
50
42
51
-
Now you'll automatically be added to CC any time alincoln creates a revision,
52
-
and can keep an eye on what he's up to.
43
+
After selecting an event, choose the type of rule to create. See "Rule Types"
44
+
below for a more detailed discussion.
53
45
54
-
= Available Actions =
46
+
Name the rule and provide conditions and actions. When events occur, the rule
47
+
will be evaluated automatically. If the conditions pass, the actions will be
48
+
taken.
55
49
56
-
Herald rules can take a number of actions. Note that some actions are only
57
-
available from Global rules, and others only from Personal rules. Additionally,
58
-
not every action is available for every object type (for instance, you can not
59
-
trigger an audit based on a Differential revision).
50
+
To test rules, use {nav Herald > Test Console}. See "Testing Rules" below
51
+
for greater detail.
60
52
61
-
- **Add CC**: Add a user or mailing list to the CC list for the object. For
62
-
personal rules, you can only add yourself.
63
-
- **Remove CC**: Remove a user or mailing list from the CC list for the
64
-
object. For personal rules, you can only remove yourself.
65
-
- **Send an Email to**: Send one email, but don't subscribe to other updates.
66
-
For personal rules, you can only email yourself.
67
-
- **Trigger an Audit**: For commits, trigger an audit request for a project
68
-
or user. For personal rules, you can only trigger an audit request to
69
-
yourself.
70
-
- **Mark with flag**: Flag the object for later review. This action is only
71
-
available on personal rules. If an object already has a flag, this action
72
-
will not add another flag.
73
-
- **Do Nothing**: Don't do anything. This can be used to disable a rule
74
-
temporarily, or to create a rule for an "Another Herald rule" condition.
53
+
To review which rules did or did not trigger for a particular event (and why),
54
+
see {nav Herald > Transcripts}.
75
55
76
-
= Testing Rules =
77
56
78
-
When you've created a rule, use the "Test Console" to test it out. Enter a
79
-
revision or commit and Herald will do a dry run against that object, showing
80
-
you which rules //would// match had it actually been updated. Dry runs executed
81
-
via the test console don't take any actions.
57
+
Rule Types
58
+
==========
82
59
83
-
= Advanced Herald =
60
+
You can create three kinds of Herald rules: personal rules, object rules, and
61
+
global rules.
62
+
63
+
- **Personal Rules** are rules owned by an individual. They're often used
64
+
to keep people informed about changes they're interested in.
65
+
- **Object Rules** are rules associated with an object (like a repository
66
+
or project). These are similar to global rules.
67
+
- **Global Rules** are apply to all objects. They're often used to block
68
+
commits or run builds.
69
+
70
+
71
+
Rule Policies
72
+
=============
73
+
74
+
All Herald rules are always visible to all users.
75
+
76
+
The edit policy for a rule depends on what type of rule it is:
77
+
78
+
- Personal rules are owned by a particular user, and can only be created or
79
+
edited by that user.
80
+
- Object rules are associated with a particular object (like a repository),
81
+
and can only be created or edited by users who can edit that object. That
82
+
is, if you can edit a repository, you can also create object rules for it
83
+
and edit existing object rules.
84
+
- Global rules are administrative and can only be created or edited by users
85
+
with the **Can Manage Global Rules** Herald application permission.
86
+
87
+
When rules are about to evaluate, they may first perform some policy tests.
88
+
89
+
- Personal rules check if the owning user can see the object which the rule
90
+
is about to run on. If the user can not see the object, the rule does not
91
+
run. This prevents individuals from writing rules which give them access
92
+
to information they don't have permission to see.
93
+
- Object and global rules **bypass policies** and always execute. This makes
94
+
them very powerful, and is why the **Can Manage Global Rules** policy is
95
+
restricted by default.
96
+
97
+
98
+
Testing Rules
99
+
=============
100
+
101
+
When you've created a rule, use the {nav Herald > Test Console} to test it out.
102
+
103
+
Enter an object name (like `D123`, `rXYZabcdef`, or `T456`) and Herald will
104
+
execute a dry run against that object, showing you which rules //would// match
105
+
had it actually been updated. Dry runs executed via the test console don't take
106
+
any actions.
107
+
108
+
109
+
Advanced Herald
110
+
===============
111
+
112
+
A few features in Herald are particularly complicated or unintuitive.
113
+
114
+
Condition **matches regexp pair**: Some conditions allow you to select the
115
+
operator "matches regexp pair". For example, you can write a rule against
116
+
revisions like this one:
117
+
118
+
> When [ all of ] these conditions are met:
119
+
> [ Changed file content ][ matches regexp pair ][ ... ]
120
+
121
+
This condition allows you to specify two regexes in JSON format. The first will
122
+
be used to match the filename of the changed file; the second will be used to
123
+
match the content. You can use these together to express conditions like
124
+
"content in Javascript files".
125
+
126
+
For example, if you want to match revisions which add or remove calls to a
127
+
"muffinize" function, //but only in JS files//, you can set the value to
128
+
`["/\\.js$/", "/muffinize/"]` or similar. This condition is satisfied only
129
+
when the filename matches the first expression and the conent matches the
130
+
second expression.
84
131
85
-
A few features in Herald are particularly complicated:
132
+
**Another Herald rule**: you can create Herald rules which depend on other
133
+
rules.
86
134
87
-
- **matches regexp pair**: for Differential revisions, you can set a condition
88
-
like "Any changed file content matches regexp pair...". This allows you to
89
-
specify two regexes in JSON format. The first will be used to match the
90
-
filename of the changed file; the second will be used to match the content.
91
-
For example, if you want to match revisions which add or remove calls to
92
-
a "muffinize" function, //but only in JS files//, you can set the value
93
-
to `["/\\.js$/", "/muffinize/"]` or similar.
94
-
- **Another Herald rule**: you can create Herald rules which depend on other
95
-
rules. This can be useful if you need to express a more complicated predicate
96
-
than "all" vs "any" allows, or have a common set of conditions which you want
97
-
to share between several rules. If a rule is only being used as a group of
98
-
conditions, you can set the action to "Do Nothing".
135
+
This can be useful if you need to express a more complicated condition
136
+
than "all" vs "any" allows, or have a common set of conditions which you want
137
+
to share between several rules.
138
+
139
+
If a rule is only being used as a group of conditions, you can set the action
140
+
to "Do Nothing".