@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 some Audit documentation
Summary:
Ref T10978.
- Generally refresh this documentation.
- Use the word "publish", not the word "push", to distinguish between review and audit, echoing the language in the "Write, Review, Merge, Publish" document.
- Mention the new "Needs Verification" state.
Test Plan: Read documentation.
Reviewers: chad
Reviewed By: chad
Maniphest Tasks: T10978
Differential Revision: https://secure.phabricator.com/D17253
+148
-70
+101
-43
src/docs/user/userguide/audit.diviner
+101
-43
src/docs/user/userguide/audit.diviner
···
1
1
@title Audit User Guide
2
2
@group userguide
3
3
4
-
Guide to the Audit (post-push code review) tool and workflow.
4
+
Guide to using Phabricator to audit published commits.
5
+
5
6
6
-
= Overview =
7
+
Overview
8
+
========
7
9
8
-
Phabricator supports two code review workflows, "review" (pre-push) and
9
-
"audit" (post-push). To understand the differences between the two, see
10
+
Phabricator supports two code review workflows, "review" (pre-publish) and
11
+
"audit" (post-publish). To understand the differences between the two, see
10
12
@{article:User Guide: Review vs Audit}.
11
13
12
-
This document summarizes the post-push "audit" workflow implemented by the
13
-
creatively-named //Audit// tool.
14
14
15
-
= How Audit Works =
15
+
How Audit Works
16
+
===============
16
17
17
-
Using auditing allows you to push and deploy code without waiting for code
18
-
review, while still doing code review eventually. The Audit tool primarily keeps
19
-
track of two things:
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:
20
47
21
48
- **Commits** and their audit state (like "Not Audited", "Approved", or
22
49
"Concern Raised").
23
-
- **Audit Requests** which ask a user (or some other entity) to audit a
24
-
commit. These can be triggered in a number of ways (see below).
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).
25
53
26
-
In the Audit tool's home screen and on the homepage you can see commits and
27
-
requests that require your action:
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:
28
58
29
-
- **Required Audits** are open audit requests that require you, a project
30
-
you are a member of, or a package you own to audit a commit. An audit
31
-
request is closed when you approve the associated commit.
32
-
- **Problem Commits** are commits you authored which someone has raised a
33
-
concern about in audit. Problem commits go away when you satisfy all the
34
-
auditors and get them to "Approve" the commit.
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 Phabrictor 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.
35
76
36
-
For example:
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:
37
81
38
-
- Evan creates commit `abcdef1234` and pushes it to the remote.
39
-
- This triggers an audit request to Bob through some mechanism (see below for
40
-
a description of trigger mechanisms).
41
-
- Later, Bob logs into Phabricator and sees the audit request on his homepage.
42
-
- Bob clicks through and examines the commit. He notices a problem, so he
43
-
selects "Raise Concern" and describes the issue in a comment.
44
-
- Evan receives an email that Bob has raised a concern about his commit. He
45
-
opts not to deal with it immediately.
46
-
- Later, Evan logs into Phabricator and sees the commit on his homepage
47
-
under "Problem Commits".
48
-
- Evan resolves the issue somehow (e.g., by discussing it with Bob, or fixing
49
-
it in another commit).
50
-
- Now satisfied, Bob "Accepts" the original commit.
51
-
- This causes the request to disappear from Bob's queue, and the commit to
52
-
disappear from Evan's queue.
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.
53
97
54
-
= Audit Triggers =
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
+
==============
55
104
56
105
Audit requests can be triggered in a number of ways:
57
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.
58
111
- If you put `Auditors: username1, username2` in your commit message, it will
59
112
trigger an audit request to those users when you push it to a tracked
60
113
branch.
61
114
- You can create rules in Herald that trigger audits based on properties
62
115
of the commit -- like the files it touches, the text of the change, the
63
116
author, etc.
64
-
- You can create an audit request for yourself by commenting on any commit.
65
-
- You can create an Owners package and select "Enable Auditing" (this is an
66
-
advanced feature which is only likely to be useful for very large teams).
117
+
- You can create an Owners package and enable automatic auditing for the
118
+
package.
67
119
68
-
= Audits in Small Teams =
120
+
121
+
Audits in Small Teams
122
+
=====================
69
123
70
124
If you have a small team and don't need complicated trigger rules, you can set
71
125
up a simple audit workflow like this:
···
84
138
Once your team gets bigger, you can refine this ruleset so that developers see
85
139
only changes that are relevant to them.
86
140
87
-
= Audit Tips =
141
+
142
+
Audit Tips
143
+
==========
88
144
89
145
- When viewing a commit, audit requests you are responsible for are
90
146
highlighted. You are responsible for a request if it's a user request
···
99
155
you submit a comment at the bottom of the page.
100
156
- Press "?" to view keyboard shortcuts.
101
157
102
-
= Next Steps =
158
+
159
+
Next Steps
160
+
==========
103
161
104
162
- Learn more about Herald at @{article:Herald User Guide}.
+47
-27
src/docs/user/userguide/reviews_vs_audit.diviner
+47
-27
src/docs/user/userguide/reviews_vs_audit.diviner
···
1
1
@title User Guide: Review vs Audit
2
2
@group userguide
3
3
4
-
Discusses the differences between Review and Audit workflows.
4
+
Discusses the differences between "review" and "audit" workflows.
5
5
6
-
= Overview =
6
+
Overview
7
+
========
7
8
8
-
Phabricator supports two similar but separate code review workflows:
9
+
Phabricator supports two similar but separate code review workflows: "review"
10
+
and "audit".
9
11
10
-
- **Differential** is used for pre-push code review, called "reviews"
11
-
elsewhere in the documentation. You can learn more in
12
-
@{article:Differential User Guide}.
13
-
- **Audit** is used for post-push code reviews, called "audits" elsewhere in
14
-
the documentation. You can learn more in @{article:Audit User Guide}.
12
+
Review occurs in **Differential**, before changes are published. You can learn
13
+
more in @{article:Differential User Guide}.
15
14
16
-
(By "pre-push", this document means review which blocks deployment of changes,
17
-
while "post-push" means review which happens after changes are deployed or
18
-
en route to deployment.)
15
+
Audit occurs in **Diffusion**, after changes are published. You can learn more
16
+
in @{article:Audit User Guide}.
19
17
20
-
Both are lightweight, asynchronous web-based workflows where reviewers/auditors
21
-
inspect code independently, from their own machines -- not synchronous review
22
-
sessions where authors and reviewers meet in person to discuss changes.
18
+
When this documentation discusses "unpublished changes", it refers to changes
19
+
which are still subject to being reworked in response to feedback. In many
20
+
workflows, these changes will only exist locally on the developer's machine,
21
+
but some workflows push tentative or temporary changes into remotes. The step
22
+
that "publishes" changes might be either pushing or merging them, depending on
23
+
your workflow.
23
24
24
-
= Advantages of Review =
25
+
Both the audit and review workflows are lightweight, asynchronous web-based
26
+
workflows where reviewers or auditors inspect code independently, from their
27
+
own machines -- not synchronous review sessions where authors and reviewers
28
+
meet in person to discuss changes.
25
29
26
-
Pre-push review is significantly more powerful than post-push auditing. You
27
-
gain these advantages by requiring review //before// changes may be pushed:
30
+
Broadly, review is normally a //blocking// workflow: in review workflows,
31
+
authors usually can not publish changes until review completes and reviewers
32
+
are satisfied.
33
+
34
+
In contrast, audit is normally a //nonblocking// workflow: in audit workflows,
35
+
changes usually move forward by default.
36
+
37
+
Advantages of Review
38
+
====================
39
+
40
+
Pre-publish review is significantly more powerful than post-publish auditing.
41
+
You gain these advantages by requiring review //before// changes may be
42
+
published:
28
43
29
44
- Authors have a strong incentive to craft small, well-formed changes that
30
45
will be readily understood, to explain them adequately, and to provide
···
32
47
- Reviewers have a real opportunity to make significant suggestions about
33
48
architecture or approach in review. These suggestions are less attractive
34
49
to adopt from audit, and may be much more difficult to adopt if significant
35
-
time has passed between push and audit.
50
+
time has passed between publish and audit.
36
51
- Authors have a strong incentive to fix problems and respond to feedback
37
-
received during review, because it blocks them. Authors have a much weaker
38
-
incentive to address problems raised during audit.
39
-
- Authors can ask reviewers to apply and verify fixes before they are pushed.
52
+
received during review because it blocks them. Authors have a much weaker
53
+
incentive to promptly address problems raised during audit.
54
+
- Authors can ask reviewers to apply and verify fixes before they are
55
+
published.
40
56
- Authors can easily pursue feedback early, and get course corrections on
41
57
approach or direction.
42
58
- Reviewers are better prepared to support a given change once it is in
···
54
70
be better spent developing. This is less true than it appears, because the costs
55
71
are low and pay for themselves in other ways:
56
72
57
-
- Differential is fast and provides a very lightweight process for submitting
73
+
- Differential is fast and provides a lightweight process for submitting
58
74
code for review and for performing review.
59
75
- Authors are free to pursue other changes while code is being reviewed. With
60
76
appropriate change management (like local branching in Git) they can even
···
87
103
- With `arc patch`, it is roughly as easy to pull a change out of Differential
88
104
as it is to pull it out of the remote.
89
105
90
-
= Advantages of Audit =
106
+
Advantages of Audit
107
+
===================
91
108
92
-
Post-push review is significantly better than nothing. If you are unpersuaded
109
+
Post-publish audit is a less powerful workflow than pre-publish review, but can
110
+
supplement review and is better than nothing on its own. If you are unpersuaded
93
111
by the arguments above (or work on a team that is unswayed), audits provide
94
112
some of the benefits of review with less friction:
95
113
96
-
- Audits are driven entirely by Phabricator, users do not need to install
114
+
- Audits are driven entirely by Phabricator: users do not need to install
97
115
`arc`.
98
116
- Audits require little adjustment to existing workflows and little training.
99
117
- Audits are completely nonblocking, and send fewer notifications than review.
···
101
119
on lower-importance changes or raise issues that are discovered after
102
120
review.
103
121
104
-
= Recommendations =
122
+
Recommendations
123
+
===============
105
124
106
125
Here are super biased recommendations from developers of code review software:
107
126
···
117
136
- If you aren't interested in review, just do audits. You can always
118
137
change your mind later. But consider review! It's really good, we promise!
119
138
120
-
= Next Steps =
139
+
Next Steps
140
+
==========
121
141
122
142
- Learn more about reviews in @{article:Differential User Guide}; or
123
143
- learn more about audits in @{article:Audit User Guide}.