1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
|
[%#
# The contents of this file are subject to the Mozilla Public
# License Version 1.1 (the "License"); you may not use this file
# except in compliance with the License. You may obtain a copy of
# the License at http://www.mozilla.org/MPL/
#
# Software distributed under the License is distributed on an "AS
# IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or
# implied. See the License for the specific language governing
# rights and limitations under the License.
#
# The Original Code is the Splinter Bugzilla Extension.
#
# The Initial Developer of the Original Code is Red Hat, Inc.
# Portions created by Red Hat, Inc. are Copyright (C) 2008
# Red Hat, Inc. All Rights Reserved.
#
# Contributor(s): Owen Taylor <otaylor@redhat.com>
#%]
[% PROCESS global/header.html.tmpl
title = "Patch Review Help"
header = "Patch Review Help"
%]
<h2>Splinter Patch Review</h2>
<p>
Splinter is an add-on for [% terms.Bugzilla %] to allow conveniently
reviewing patches that people have attached to
[%+ terms.Bugzilla %]. <a href="http://fishsoup.net/software/splinter">More
information about Splinter</a>.
</p>
<h3>The patch review view</h3>
<p>
If you get to Splinter by clicking on a link next to an
attachment in [% terms.Bugzilla %], you are presented with the patch
review view. This view has a number of different pages that can
be switched between with the links at the top of the screen.
The first page is the Overview page, the other pages correspond to
individual files changed by the review.
</p>
<p>
On the Overview page, from top to bottom are shown:
</p>
<ul>
<li>Introductory text to the patch. For a patch that was created
using 'git format-patch' this will be the Git commit
message.</li>
<li>Controls for creating a new review</li>
<li>Previous reviews that other people have written.</li>
</ul>
<p>
The pages for each file show a two-column view of the changes.
The left column is the previous contents of the file,
the right column is the new contents of the file. (If the file
is an entirely new file or an entirely deleted file, only one
column will be shown.) Red indicates lines that have been
removed, green lines that have been added, and blue lines that
were modified.
</p>
<p>
If people have previously made comments on individual lines of
the patch, they will show up both summarized on the Overview
page and also inline when looking at the files of the patch.
</p>
<h3>Reviewing an existing patch</h3>
<p>
There are three components to a review:
</p>
<ul>
<li>
An overall comment. The text area on the first page allows
you to enter your overall thoughts on the [% terms.bug %].
</li>
<li>
Detailed comments on changes within the files. To comment on a
line in a patch, double click on it, and a text area will open
beneath that comment. When you are done, click the Save button
to save your comment or the Cancel button to throw your
comment away. You can double-click on a saved comment to start
editing it again and make further changes.
</li>
<li>
A change to the attachment status. (This is specific to
[%+ terms.Bugzilla %] instances that have attachment status, which is a
non-upstream patch. It's somewhat similar to attachment flags,
which splinter doesn't currently support displaying or
changing.) This allows you to mark a patch as read to commit
or needing additional work. This is done by changing the
drop-down next to the Publish button.
</li>
</ul>
<p>
Once you are done writing your review, go back to Overview page
and click the "Publish" button to submit it as a comment on the
[%+ terms.bug %]. The comment will have a link back to the review page so
that people can see your comments with the full context.
</p>
<h3>Saved drafts</h3>
<p>
Whenever you start making changes, a draft is automatically
saved. If you come back to the patch review page for the same
attachment, that draft will automatically be resumed. Drafts are
not visible to anybody else until published.
</p>
<p>
Note that saving drafts requires the your browser to have support
for the "DOM Storage" standard. At time of writing, this is
available only in a few very recent browsers, like Firefox
3.5. Strict privacy protections like disabling cookies may also
disable DOM Storage, since it provides another mechanism for
sites to track information about their users.
</p>
<h3>Responding to someone's review</h3>
<p>
A response is treated just like any other review and created the
same way. A couple of features are helpful when responding: you
can double-click on an inline comment to respond to it. And on
the overview page, when you click on a detailed comment, you are
taken directly to the original location of the comment.
</p>
<h3>Uploading patches for review</h3>
<p>
Splinter doesn't really care how patches are provided to
[%+ terms.Bugzilla %], as long as they are well-formatted patches. If you are
using Git for version control, you can either format changes as
patches
using <a href="http://www.kernel.org/pub/software/scm/git/docs/git-format-patch.html">'git
format-patch</a> and attach them manually to the [% terms.bug %], or you
can
use <a href="http://fishsoup.net/software/git-bz">git-bz</a>.
git-bz is highly recommended; it automates most of the steps
that Splinter can't handle: it files new [% terms.bugs %], attaches updated
attachments to existing [% terms.bugs %], and closes [% terms.bugs %] when you push the
corresponding git commits to your central repository.
</p>
<h3>The [% terms.bug %] review view</h3>
<p>
Splinter also has a view where it shows all patches attached to
the [% terms.bug %] with their status and links to review them. You are
taken to this page after publishing a review. You can also get
to this page with the [% terms.bug %] link in the upper-right corner of the
patch review view.
</p>
<h3>Your reviews</h3>
<p>
Splinter can also show you a list of all your draft and
published reviews. Access this page with the "Your reviews"
link at the bottom of the [% terms.bug %] review view. In-progress drafts
are shown in bold.
</p>
[% PROCESS global/footer.html.tmpl %]
|
