.\" .\" CDDL HEADER START .\" .\" The contents of this file are subject to the terms of the .\" Common Development and Distribution License (the "License"). .\" You may not use this file except in compliance with the License. .\" .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE .\" or http://www.opensolaris.org/os/licensing. .\" See the License for the specific language governing permissions .\" and limitations under the License. .\" .\" When distributing Covered Code, include this CDDL HEADER in each .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE. .\" If applicable, add the following below this CDDL HEADER, with the .\" fields enclosed by brackets "[]" replaced with your own identifying .\" information: Portions Copyright [yyyy] [name of copyright owner] .\" .\" CDDL HEADER END .\" .\" Copyright 2008 Sun Microsystems, Inc. All rights reserved. .\" Use is subject to license terms. .\" .\" .TH webrev 1 "12 August 2008" .SH NAME webrev \- Generate HTML codereview materials .SH SYNOPSIS .B webrev [ .I common-options ] .B webrev [ .I common-options ] .I file-list-file | .I - .B webrev [ .I common-options ] .B -w .I wx-file .B webrev [ .I common-options ] .B -l .I arguments to 'putback' See OPTIONS for common-options. Note that the -l option is only applicable to TeamWare workspaces. .SH DESCRIPTION .B webrev builds a set of HTML files suitable for performing code review of source changes in a web browser. It supports Mercurial, Subversion and Teamware repositories. At its most basic, usage is: .nf $ webrev .fi In which case \fBwebrev\fR attempts to figure out the list of files for review (note that when using Teamware \fBputback\fR, this may take a long time; see the -l option). If that fails, or if more control over the set of files is needed, a \fIfile list\fR may be specified. \fBwebrev\fR also attempts to deduce a .I basis for comparison (interchangeably called the \fIparent\fR, but see SCM INTERACTIONS below). A basis for comparison is needed in order to determine the differences introduced by the code changes under review. By default, \fBwebrev\fR creates a \fIwebrev\fR directory in the workspace directory that contains the generated HTML files, a generated PDF review, and a patch representing the changes. It also places a copy of the file list in that directory, and of both the old and new raw files in the \fB$webrev_root/raw_files\fR directory. To output the webrev somewhere other than the default location, use the \fI-o \fR option, or set the \fBWDIR\fR environment variable. For example: .nf $ webrev -o ~/public_html/myreview/ .fi .PP In the index file, each file is listed on a line with a link to the relevant review materials. Comments for each delta will be included automatically. Bug numbers (any sequence of 5 or more digits) and ARC cases (ARC name followed by year/number, e.g. PSARC/2003/436) in the comment will become hyperlinks in the associated web interface. As a review aid, content may be added to the \fIindex\fR file in two ways. First, the author may manually edit the file (for example by including text that explains the changes in front of the links for each file). Note that if webrev is run again, manual edits will be lost. Second, if a file named \fIwebrev-info\fR is present at the root of the workspace, it will be automatically included in the \fIindex\fR file. To include a different file, see the \fI-i\fR option. For each file in the file list, \fBwebrev\fR compares the file with the version in the basis for comparison (i.e. the parent workspace) and generates a variety of HTML renderings of the differences between the two files; which of these renderings to use is largely a matter of personal preference. Additional, webrev emits a patch, the old and new versions of the file, and a "raw" copy of the file which is suitable for download. For files which express differences, source is formatted according to the following color coding: .IP .nf unchanged : black removed : brown changed : blue new : bold blue .fi .SH SCM INTERACTIONS .PP .B webrev attempts to interact with the source code management system currently in use. .B webrev needs to be able locate the code under review (i.e. the workspace) and the basis for comparison (i.e. the parent). The method for doing so depends upon the SCM in use, which .B webrev will also attempt to auto-discover. In all cases, .B webrev must either discover the list of files which have changed, or else this list must be manually specified, either in "webrev file list" format or in "wx" format. See FILE LIST for more details. .PP In all cases, if the user has activated the workspace with the .BR ws (1) or .BR bldenv (1) commands, \fBwebrev\fR will use the \fBCODEMGR_PARENT\fR and \fBCODEMGR_WS\fR environment variables to identify parent and child workspaces respectively. To manually specify the basis for comparison, use the -p option or specify the \fBCODEMGR_PARENT\fR variable in either the file list or the environment. .SS Discovering the SCM in use. .B webrev makes use of .BR which_scm (1) to determine the SCM in use for a given workspace. .SS TeamWare In the case of TeamWare \fBwebrev\fR will use the output of "workspace name" to discover the workspace root, if not otherwise specified. .PP \fBwebrev\fR will attempt to use a .BR wx (1) active list in \fBCODEMGR_WS/wx/active\fR. To direct \fBwebrev\fR to determine the file list from the output of .BR putback "(1)," use the -l option. (Note that \fBwebrev\fR may also elect to use \fBputback\fR if it cannot determine the file list from .BR wx "(1))." The -l option indicates that subsequent arguments should be treated as arguments to .BR putback "(1)." This can be used to prune the set of files which putback examines, or to reference a teamware flp (file list program). .SS Mercurial In the case of Mercurial \fBwebrev\fR will attempt to use the output from the .BR hg (1) "hg root" to identify the workspace root, and the "hg path default" command to identify the parent workspace. .SS Subversion In the case of Subversion \fBwebrev\fR will attempt to use the output from the .BR svn (1) "svn info" to find the workspace root and subversion repository URL. .PP The file list will be created from the output of the "svn status" command. .SH OPTIONS .TP 10 .BI "-w " wx-file Extract the file list from the wx "active" file specified. 'wx' uses this mode when invoking webrev. The list is assumed to be in the format expected by the \fIwx\fR package. See FILE LIST, below. .TP 10 .BI "-l " putback-args Extract the file list from the output of .I putback -n. Any arguments supplied will be passed to .BR putback "(1)." See SCM INTERACTIONS. For more information about file lists, see FILE LIST. This argument should appear last. .TP 10 .B -O Enable \fIOpenSolaris\fR mode: bug links are generated relative to \fIbugs.opensolaris.org\fR, SAC links are generated relative to \fIwww.opensolaris.org\fR, and sources which appear in \fIusr/closed\fR are automatically elided from the review. .TP 10 .BI "-i " include-file Include the specified file into the index.html file which is generated as part of the webrev. This allows a snippet of XHTML to be added by the webrev author. User content is contained by a
tag and the markup should validate as XHTML 1.0 Transitional. .TP 10 .BI "-o " output-dir Place output from running the script in the directory specified. If specified, this option takes precedence over the WDIR environment variable. .TP 10 .BI "-p " basis-of-comparison Specify a basis of comparison meaningful for the SCM currently in use. See SCM INTERACTIONS and INCREMENTAL REVIEWS. .TP 10 .BI "-N" Suppress all comments from all output forms html, txt and pdf. .SH FILE LIST .PP .B Webrev needs to be told or to discover which files have changed in a given workspace. By default, .B webrev will attempt to autodetect the list of changed files by first consulting .BR wx "(1)." If this information is not available, webrev tries to consult the SCM (Source Code Manager) currently in use. If that fails, the user must intervene by specifying either a file list or additional options specific to the SCM in use. .SS Webrev Format A webrev formatted file list contains a list of all the files to be included in the review with paths relative to the workspace directory, e.g. .IP .nf \f(CWusr/src/uts/common/fs/nfs/nfs_subr.c usr/src/uts/common/fs/nfs/nfs_export.c usr/src/cmd/fs.d/nfs/mountd/mountd.c .fi .PP Include the paths of any files added, deleted, or modified. You can keep this list of files in the webrev directory that webrev creates in the workspace directory (CODEMGR_WS). If CODEMGR_WS is not set, it may be specified as an environment variable within the file list, e.g. .IP .nf \f(CWCODEMGR_WS=/home/brent/myws usr/src/uts/common/fs/nfs/nfs_subr.c usr/src/uts/common/fs/nfs/nfs_export.c usr/src/cmd/fs.d/nfs/mountd/mountd.c .fi .PP To compare the workspace against one other than the parent (see also the -p option), include a CODEMGR_PARENT line in the file list, like: .IP .nf \f(CWCODEMGR_WS=/home/brent/myws CODEMGR_PARENT=/ws/onnv-gate usr/src/uts/common/fs/nfs/nfs_subr.c usr/src/uts/common/fs/nfs/nfs_export.c usr/src/cmd/fs.d/nfs/mountd/mountd.c .fi .PP Finally, run webrev with the name of the file containing the file list as an argument, e.g. .nf $ webrev file.list .fi .PP If "-" is supplied as the name of the file, then stdin will be used. .SS wx Format If the \fI-w\fR flag is specified then \fBwebrev\fR will assume the file list is in the format expected by the "wx" package: pathname lines alternating with SCCS comment lines separated by blank lines, e.g. .IP .nf \f(CWusr/src/uts/common/fs/nfs/nfs_subr.c 1206578 Fix spelling error in comment usr/src/uts/common/fs/nfs/nfs_export.c 4039272 cstyle fixes usr/src/cmd/fs.d/nfs/mountd/mountd.c 1927634 mountd daemon doesn't handle expletives .fi .SH INCREMENTAL REVIEWS When conducting multiple rounds of code review, it may be desirable to generate a webrev which represents the delta between reviews. In this case, set the parent workspace to the path to the old webrev: .IP .nf \f(CW$ webrev -o ~/public_html/myreview-rd2/ \\ -p ~/public_html/myreview/ .fi .SH ENVIRONMENT VARIABLES The following environment variables allow for customization of \fBwebrev\fR: .PP \fBCDIFFCMD\fR and \fBUDIFFCMD\fR are used when generating Cdiffs and Udiffs respectively; their default values are "diff -b -C 5" and "diff -b -U 5". To generate diffs with more (or less) than 5 lines of context or with more (or less) strict whitespace handling, set one or both of these variables in the user environment accordingly. \fBWEBREV_BUGURL\fR may be set to an alternate bug-to-HTML interface (providing the BUG number can be appended to the URL). The default URL is "http://monaco.sfbay.sun.com/detail.jsp?cr=". \fBWDIR\fR sets the output directory. It is functionally equivalent to the \fI-o\fR option. \fBWDIFF\fR specifies the command used to generate Wdiffs. Wdiff generates a full unified context listing with line numbers where unchanged sections of code may be expanded and collapsed. It also provides a "split" feature that shows the same file in two HTML frames one above the other. The default path for this script is /ws/onnv-gate/public/bin/wdiff but WDIFF may be set to customize this to use a more convenient location. .SH SEE ALSO .BR putback "(1)," .BR workspace "(1)," .BR hg "(1)," .BR svn "(1)," .BR which_scm "(1)" .SH ACKNOWLEDGEMENTS Acknowledgements to Rob Thurlow, Mike Eisler, Lin Ling, Rod Evans, Mike Kupfer, Greg Onufer, Glenn Skinner, Oleg Larin, David Robinson, Matthew Cross, David L. Paktor, Neal Gafter, John Beck, Darren Moffat, Norm Shulman, Bill Watson, Pedro Rubio and Bill Shannon for valuable feedback and insight in building webrev. Have fun! .br Brent Callaghan 11/28/96