AF:
NF:0
PS:10
SRH:1
SFN:
DSR:
MID:<20080116142605.4f5fa1ff@ripper.onstor.net>
CFG:
PT:0
S:andy.sharp@onstor.com
RQ:
SSV:onstor-exch02.onstor.net
NSV:
SSH:
R:<dl-software>,<warren.gale@onstor.com>,<brian.stark@onstor.com>,<rick.lund@onstor.com>
MAID:1
X-Sylpheed-Privacy-System:
X-Sylpheed-Sign:0
SCF:#mh/Mailbox/sent
X-Sylpheed-End-Special-Headers: 1
Date: Wed, 16 Jan 2008 14:27:23 -0800
From: Andrew Sharp <andy.sharp@onstor.com>
To: dl-software
Cc: Warren Gale <warren.gale@onstor.com>, Brian Stark
 <brian.stark@onstor.com>, Rick Lund <rick.lund@onstor.com>
Subject: code review helper script
Message-ID: <20080116142723.1ee6b37d@ripper.onstor.net>
Organization: Onstor
X-Mailer: Sylpheed-Claws 2.6.0 (GTK+ 2.8.20; x86_64-pc-linux-gnu)
Mime-Version: 1.0
Content-Type: text/plain; charset=US-ASCII
Content-Transfer-Encoding: 7bit

I have been hacking on a code review helper script for a while now, and
find that I use it a lot and that it saves me an enormous amount of
time.  It's been especially helpful when I'm remotely logged in via
ssh and have a code review to do.  I've given it to a couple of people
who have found it useful, so I thought I would make it generally
available.  It can be found here:

/n/software/dev-tools/code-review-script.sh

It is the kind of script that people will probably want to tinker with
a little bit to personalize it.  Two things that are likely candidates
to change: the diffing program and the file where the comments are
stored.

You'll notice that there are about 5 different "diff_prog=foo" lines.
Obviously the last one is the one that sticks.  I've made it the
perforce GUI diff program because I figure a lot of people use that.  I
personally use tkdiff, but that isn't on our workstations unless you
add it yourself.  I've included a few other known options, like
kcompare from the kde environment, gvim has a diff mode, and obviously
so does emacs.  Customize to suit!

There are a few other options or you can add your own.  The comments
are stored in file called ~/devnotes/review_{changelist#}.out.  You can
customize that by changing the variable OUTFILE.  gvim is used to edit
the review comments for each file.  You can change that to some other
program by setting the edit_prog (and variations) variable.

Here's how it works: what you do is get a changelist # from someone who
wants you to review their code changes.   They have to bottle up their
changes into a separate change list # using the "p4 change" command or
by using p4v. Then you start the review by running the script with the
changelist# as the only argument:

$ code-review-script.sh 26969

For each file that has been edited, two windows pop up: one is the diff
program showing the changes in question, the other is an editor window
into which you type just your comments for this file.  I has "looks
good" as the seed value, which you change if it doesn't look good ~:^)

If you enter the word "stop" as the first text in the comments, then
the review script will exit.  It saves the comments you have written up
to that file, and you can start the review again later and pick up
where you left off.  After you start the script, you can use CTRL-Z/bg
to put it in background so you can use that text window for other
things, or you can modify the script to always run in background.

It continues on to the next file when you close the comments editor
window.  It does not close the diff program window for you.

For files that are added or integrated/branched, instead of a diff
window, it pops up a read-only editor window containing the contents of
the new file.

When you have finished the last file, the script wraps and coalesces
all your comments by file into a single file, the name of which I
already mentioned.  Each file name is left justified followed by the
comments for that file indented below it.  I typically just insert the
contents of that file into the email I send in response to the review
request. Of course you can edit it and whatever before you send it, or
not even send it, say, for instance if the code all looks good, no need
to send 25 lines saying every file looks good.  But if you do, at least
the reviewee knows you looked at every file.

The two requirements of the review requester are that the files be
accessible on a publicly mounted/automountable directory (like your
home directory, where your changes should always be kept anyway, for
snapshot and backup reasons, regardless of your build requirements),
and that the changes be captured in a separate changelist.  The
reviewer can run the script from any arbitrary directory.

If this helps anyone or saves anyone some time, then great.  I just
thought I would make it available.  If I gave you the script already,
then this version is probably better because I think I've fixed a
couple of bugs since the last time I gave it to anyone.  The "resume"
feature definitely works properly finally.

Cheers,

a

PS.  The script can also be used for looking at the diffs for an already
commited changelist, but with the caveat that you see the differences
since before that changelist up to the latest version synced by that
client, not just between that changelist and the previous version.  But
it was never meant for that anyway....
