[Summary view] [Print] [Text view]

   1  @title Herald User Guide
   2  @group userguide
   3  
   4  Use Herald to get notified of changes you care about.
   5  
   6  = Overview =
   7  
   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.
  12  
  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.
  18  
  19  = Global and Personal Rules =
  20  
  21  You can create two kinds of Herald rules, //global// and //personal//:
  22  
  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.
  29  
  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.
  33  
  34  = Rules, Conditions and Actions =
  35  
  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.
  40  
  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.
  43  
  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.
  50  
  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.
  53  
  54  = Available Actions =
  55  
  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).
  60  
  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.
  75  
  76  = Testing Rules =
  77  
  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.
  82  
  83  = Advanced Herald =
  84  
  85  A few features in Herald are particularly complicated:
  86  
  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".