@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
1@title Herald User Guide
2@group userguide
3
4Use Herald to get notified of changes you care about.
5
6Overview
7========
8
9Herald allows you to write rules which run automatically when objects (like
10tasks or commits) are created or updated. For instance, you might want to get
11notified every time someone sends out a revision that affects some file you're
12interested in, even if they didn't add you as a reviewer.
13
14One way to think about Herald is that it is a lot like the mail rules you can
15set up in most email clients to organize mail based on "To", "Subject", etc.
16Herald works very similarly, but operates on Phorge objects (like revisions
17and commits) instead of emails.
18
19For example, you can write a personal rule like this which triggers on tasks:
20
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 ]
25
26This rule will automatically subscribe you to any newly created or updated
27tasks that contain "quasar" in the title.
28
29Herald rules are often used to: notify users, add reviewers, initiate audits,
30classify objects, block commits, enforce CLAs, and run builds.
31
32
33Working with Rules
34==================
35
36To create new Herald rules, navigate to the {nav Herald} application and select
37{nav Create Herald Rule}.
38
39Next, you'll choose an event that you want to write a rule for: for example,
40a rule for when commits are discovered or a rule for when tasks are created or
41updated.
42
43After selecting an event, choose the type of rule to create. See "Rule Types"
44below for a more detailed discussion.
45
46Name the rule and provide conditions and actions. When events occur, the rule
47will be evaluated automatically. If the conditions pass, the actions will be
48taken.
49
50To test rules, use {nav Herald > Test Console}. See "Testing Rules" below
51for greater detail.
52
53To review which rules did or did not trigger for a particular event (and why),
54see {nav Herald > Transcripts}.
55
56
57Rule Types
58==========
59
60You can create three kinds of Herald rules: personal rules, object rules, and
61global 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
71Rule Policies
72=============
73
74All Herald rules are always visible to all users.
75
76The 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
87When 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
98Testing Rules
99=============
100
101When you've created a rule, use the {nav Herald > Test Console} to test it out.
102
103Enter an object name (like `D123`, `rXYZabcdef`, or `T456`) and Herald will
104execute a dry run against that object, showing you which rules //would// match
105had it actually been updated. Dry runs executed via the test console don't take
106any actions.
107
108
109Action Repetition Settings
110==========================
111
112Rules can be configured to act in different ways:
113
114**Every time the rule matches:** The rule will take actions every time the
115object is updated if the rule's conditions match the current object state.
116
117**Only the first time the rule matches:** The rule will take actions only once
118per object, regardless of how many times the object is updated. After the rule
119acts once, it won't run on the same object again.
120
121**If this rule did not match the last time:** This rule will take actions the
122first time it matches for an object. After that, it won't act unless the object
123just changed from not matching to matching.
124
125For example, suppose you have a rule like this:
126
127> When:
128> [ Title ][ contains ][ duck ]
129> Take actions [ if this rule did not match the last time: ]
130> [ Add comment ][ "Please prefer the term 'budget goose'." ]
131
132If you set this rule to act "every time", it will leave a comment on the task
133for every single update until the title is edited. This is usually pretty noisy.
134
135If you set this rule to act "only the first time", it will only leave one
136comment. This fixes the noise problem, but creates a new problem: if someone
137edits the title, then a later change breaks it again, the rule won't leave
138another reminder comment.
139
140If you set this rule to act "if it did not match the last time", it will leave
141one comment on matching tasks. If the task is fixed (by replacing the term
142"duck" with the term "budget goose", so the object no longer matches the rule)
143and then later changed to violate the rule again (by putting the term
144"duck" back in the title), the rule will act again.
145
146
147Advanced Herald
148===============
149
150A few features in Herald are particularly complicated or unintuitive.
151
152Condition **matches regexp pair**: Some conditions allow you to select the
153operator "matches regexp pair". For example, you can write a rule against
154revisions like this one:
155
156> When [ all of ] these conditions are met:
157> [ Changed file content ][ matches regexp pair ][ ... ]
158
159This condition allows you to specify two regexes in JSON format. The first will
160be used to match the filename of the changed file; the second will be used to
161match the content. You can use these together to express conditions like
162"content in Javascript files".
163
164For example, if you want to match revisions which add or remove calls to a
165"muffinize" function, //but only in JS files//, you can set the value to
166`["/\\.js$/", "/muffinize/"]` or similar. This condition is satisfied only
167when the filename matches the first expression and the content matches the
168second expression.
169
170**Another Herald rule**: you can create Herald rules which depend on other
171rules.
172
173This can be useful if you need to express a more complicated condition
174than "all" vs "any" allows, or have a common set of conditions which you want
175to share between several rules.
176
177If a rule is only being used as a group of conditions, you can set the action
178to "Do Nothing".