[Summary view] [Print] [Text view]

   1  @title Audit User Guide
   2  @group userguide
   3  
   4  Guide to the Audit (post-push code review) tool and workflow.
   5  
   6  = Overview =
   7  
   8  Phabricator supports two code review workflows, "review" (pre-push) and
   9  "audit" (post-push). To understand the differences between the two, see
  10  @{article:User Guide: Review vs Audit}.
  11  
  12  This document summarizes the post-push "audit" workflow implemented by the
  13  creatively-named //Audit// tool.
  14  
  15  NOTE: The audit workflow is new, give us feedback about it! See
  16  @{article:Give Feedback! Get Support!}.
  17  
  18  = How Audit Works =
  19  
  20  Using auditing allows you to push and deploy code without waiting for code
  21  review, while still doing code review eventually. The Audit tool primarily keeps
  22  track of two things:
  23  
  24    - **Commits** and their audit state (like "Not Audited", "Approved", or
  25      "Concern Raised").
  26    - **Audit Requests** which ask a user (or some other entity) to audit a
  27      commit. These can be triggered in a number of ways (see below).
  28  
  29  In the Audit tool's home screen (at `/audit/`) and on the homepage you can see
  30  commits and requests that require your action:
  31  
  32    - **Required Audits** are open audit requests that require you, a project
  33      you are a member of, or a package you own to audit a commit. An audit
  34      request is closed when you approve the associated commit.
  35    - **Problem Commits** are commits you authored which someone has raised a
  36      concern about in audit. Problem commits go away when you satisfy all the
  37      auditors and get them to "Approve" the commit.
  38  
  39  For example:
  40  
  41    - Evan creates commit `abcdef1234` and pushes it to the remote.
  42    - This triggers an audit request to Bob through some mechanism (see below for
  43      a description of trigger mechanisms).
  44    - Later, Bob logs into Phabricator and sees the audit request on his homepage.
  45    - Bob clicks through and examines the commit. He notices a problem, so he
  46      selects "Raise Concern" and describes the issue in a comment.
  47    - Evan receives an email that Bob has raised a concern about his commit. He
  48      opts not to deal with it immediately.
  49    - Later, Evan logs into Phabricator and sees the commit on his homepage
  50      under "Problem Commits".
  51    - Evan resolves the issue somehow (e.g., by discussing it with Bob, or fixing
  52      it in another commit).
  53    - Now satisfied, Bob "Accepts" the original commit.
  54    - This causes the request to disappear from Bob's queue, and the commit to
  55      disappear from Evan's queue.
  56  
  57  = Audit Triggers =
  58  
  59  Audit requests can be triggered in a number of ways:
  60  
  61    - If you put `Auditors: username1, username2` in your commit message, it will
  62      trigger an audit request to those users when you push it to a tracked
  63      branch.
  64    - You can create rules in Herald that trigger audits based on properties
  65      of the commit -- like the files it touches, the text of the change, the
  66      author, etc.
  67    - You can create an audit request for yourself by commenting on any commit.
  68    - You can create an Owners package and select "Enable Auditing" (this is an
  69      advanced feature which is only likely to be useful for very large teams).
  70  
  71  = Audits in Small Teams =
  72  
  73  If you have a small team and don't need complicated trigger rules, you can set
  74  up a simple audit workflow like this:
  75  
  76    - Create a new Project, "Code Audits".
  77    - Create a new global Herald rule for Commits, which triggers an audit by
  78      the "Code Audits" project for every commit where "Differential Revision"
  79      "does not exist" (this will allow you to transition partly or fully to
  80      review later if you want).
  81    - Have every engineer join the "Code Audits" project.
  82  
  83  This way, everyone will see an audit request for every commit, but it will be
  84  dismissed if anyone approves it. Effectively, this enforces the rule "every
  85  commit should have //someone// look at it".
  86  
  87  Once your team gets bigger, you can refine this ruleset so that developers see
  88  only changes that are relevant to them.
  89  
  90  = Audit Tips =
  91  
  92    - When viewing a commit, audit requests you are responsible for are
  93      highlighted. You are responsible for a request if it's a user request
  94      and you're that user, or if it's a project request and you're a member
  95      of the project, or if it's a package request and you're a package owner.
  96      Any action you take will update the state of all the requests you're
  97      responsible for.
  98    - You can leave inline comments by clicking the line numbers in the diff.
  99    - You can leave a comment across multiple lines by dragging across the line
 100      numbers.
 101    - Inline comments are initially saved as drafts. They are not submitted until
 102      you submit a comment at the bottom of the page.
 103    - Press "?" to view keyboard shortcuts.
 104  
 105  = Next Steps =
 106  
 107    - Learn more about Herald at @{article:Herald User Guide}; or
 108    - give us feedback at @{article:Give Feedback! Get Support!}.