src/docs/user/userguide/audit.diviner

   1 @title Audit User Guide
   2 @group userguide
   3
   4 Guide to using Phabricator to audit published commits.
   5
   6
   7 Overview
   8 ========
   9
  10 Phabricator supports two code review workflows, "review" (pre-publish) and
  11 "audit" (post-publish). To understand the differences between the two, see
  12 @{article:User Guide: Review vs Audit}.
  13
  14
  15 How Audit Works
  16 ===============
  17
  18 The audit workflow occurs after changes have been published. It provides ways
  19 to track, discuss, and resolve issues with commits that are discovered after
  20 they go through whatever review process you have in place (if you have one).
  21
  22 Two examples of how you might use audit are:
  23
  24 **Fix Issues**: If a problem is discovered after a change has already been
  25 published, users can find the commit which introduced the problem and raise a
  26 concern on it. This notifies the author of the commit and prompts them to
  27 remedy the issue.
  28
  29 **Watch Changes**: In some cases, you may want to passively look over changes
  30 that satisfy some criteria as they are published. For example, you may want to
  31 review all Javascript changes at the end of the week to keep an eye on things,
  32 or make sure that code which impacts a subsystem is looked at by someone on
  33 that team, eventually.
  34
  35 Developers may also want other developers to take a second look at things if
  36 they realize they aren't sure about something after a change has been published,
  37 or just want to provide a heads-up.
  38
  39 You can configure Herald rules and Owners packages to automatically trigger
  40 audits of commits that satisfy particular criteria.
  41
  42
  43 Audit States and Actions
  44 ========================
  45
  46 The audit workflow primarily keeps track of two things:
  47
  48   - **Commits** and their audit state (like "Not Audited", "Approved", or
  49     "Concern Raised").
  50   - **Audit Requests** which ask a user (or some other entity, like a project
  51     or package) to audit a commit. These can be triggered in a number of ways
  52     (see below).
  53
  54 Users interact with commits by leaving comments and applying actions, like
  55 accepting the changes or raising a concern. These actions change the state of
  56 their own audit and the overall audit state of the commit. Here's an example of
  57 a typical audit workflow:
  58
  59   - Alice publishes a commit containing some Javascript.
  60   - This triggers an audit request to Bailey, the Javascript technical
  61     lead on the project (see below for a description of trigger mechanisms).
  62   - Later, Bailey logs into Phabricator and sees the audit request. She ignores
  63     it for the moment, since it isn't blocking anything. At the end of the
  64     week she looks through her open requests to see what the team has been
  65     up to.
  66   - Bailey notices a few minor problems with Alice's commit. She leaves
  67     comments describing improvements and uses "Raise Concern" to send the
  68     commit back into Alice's queue.
  69   - Later, Alice logs into Phabricator and sees that Bailey has raised a
  70     concern (usually, Alice will also get an email). She resolves the issue
  71     somehow, maybe by making a followup commit with fixes.
  72   - After the issues have been dealt with, she uses "Request Verification" to
  73     return the change to Bailey so Bailey can verify that the concerns have
  74     been addressed.
  75   - Bailey uses "Accept Commit" to close the audit.
  76
  77 In {nav Diffusion > Browse Commits}, you can review commits and query for
  78 commits with certain audit states. The default "Active Audits" view shows
  79 all of the commits which are relevant to you given their audit state, divided
  80 into buckets:
  81
  82   - **Needs Attention**: These are commits which you authored that another
  83     user has raised a concern about: for example, maybe they believe they have
  84     found a bug or some other problem. You should address the concerns.
  85   - **Needs Verification**: These are commits which someone else authored
  86     that you previously raised a concern about. The author has indicated that
  87     they believe the concern has been addressed. You should verify that the
  88     remedy is satisfactory and accept the change, or raise a further concern.
  89   - **Ready to Audit**: These are commits which someone else authored that you
  90     have been asked to audit, either by a user or by a system rule. You should
  91     look over the changes and either accept them or raise concerns.
  92   - **Waiting on Authors**: These are commits which someone else authored that
  93     you previously raised a concern about. The author has not responded to the
  94     concern yet. You may want to follow up.
  95   - **Waiting on Auditors**: These are commits which you authored that someone
  96     else needs to audit.
  97
  98 You can use the query constraints to filter this list or find commits that
  99 match certain criteria.
 100
 101
 102 Audit Triggers
 103 ==============
 104
 105 Audit requests can be triggered in a number of ways:
 106
 107   - You can add auditors explicitly from the web UI, using either "Edit Commit"
 108     or the "Change Auditors" action. You might do this if you realize you are
 109     not sure about something that you recently published and want a second
 110     opinion.
 111   - If you put `Auditors: username1, username2` in your commit message, it will
 112     trigger an audit request to those users when you push it to a tracked
 113     branch.
 114   - You can create rules in Herald that trigger audits based on properties
 115     of the commit -- like the files it touches, the text of the change, the
 116     author, etc.
 117   - You can create an Owners package and enable automatic auditing for the
 118     package.
 119
 120
 121 Audits in Small Teams
 122 =====================
 123
 124 If you have a small team and don't need complicated trigger rules, you can set
 125 up a simple audit workflow like this:
 126
 127   - Create a new Project, "Code Audits".
 128   - Create a new global Herald rule for Commits, which triggers an audit by
 129     the "Code Audits" project for every commit where "Differential Revision"
 130     "does not exist" (this will allow you to transition partly or fully to
 131     review later if you want).
 132   - Have every engineer join the "Code Audits" project.
 133
 134 This way, everyone will see an audit request for every commit, but it will be
 135 dismissed if anyone approves it. Effectively, this enforces the rule "every
 136 commit should have //someone// look at it".
 137
 138 Once your team gets bigger, you can refine this ruleset so that developers see
 139 only changes that are relevant to them.
 140
 141
 142 Audit Tips
 143 ==========
 144
 145   - When viewing a commit, audit requests you are responsible for are
 146     highlighted. You are responsible for a request if it's a user request
 147     and you're that user, or if it's a project request and you're a member
 148     of the project, or if it's a package request and you're a package owner.
 149     Any action you take will update the state of all the requests you're
 150     responsible for.
 151   - You can leave inline comments by clicking the line numbers in the diff.
 152   - You can leave a comment across multiple lines by dragging across the line
 153     numbers.
 154   - Inline comments are initially saved as drafts. They are not submitted until
 155     you submit a comment at the bottom of the page.
 156   - Press "?" to view keyboard shortcuts.
 157
 158
 159 Audit Maintenance
 160 =================
 161
 162 The `bin/audit` command allows you to perform several maintenance operations.
 163 Get more information about a command by running:
 164
 165 ```
 166 phabricator/ $ ./bin/audit help <command>
 167 ```
 168
 169 Supported operations are:
 170
 171 **Delete Audits**: Delete audits that match certain parameters with
 172 `bin/audit delete`.
 173
 174 You can use this command to forcibly delete requests which may have triggered
 175 incorrectly (for example, because a package or Herald rule was configured in an
 176 overbroad way).
 177
 178 **Synchronize Audit State**: Synchronize the audit state of commits to the
 179 current open audit requests with `bin/audit synchronize`.
 180
 181 Normally, overall audit state is automatically kept up to date as changes are
 182 made to an audit. However, if you manually update the database to make changes
 183 to audit request state, the state of corresponding commits may no longer be
 184 consistent.
 185
 186 This command will update commits so their overall audit state reflects the
 187 cumulative state of their actual audit requests.
 188
 189 **Update Owners Package Membership**: Update which Owners packages commits
 190 belong to with `bin/audit update-owners`.
 191
 192 Normally, commits are automatically associated with packages when they are
 193 imported. You can use this command to manually rebuild this association if
 194 you run into problems with it.
 195
 196 Next Steps
 197 ==========
 198
 199   - Learn more about Herald at @{article:Herald User Guide}.