tools/devel/review/00-README | 77 ++++++------------------------------- tools/devel/review/commit.template | 51 ++++++++++++++++++++++-- tools/devel/review/hgeditor.sh | 32 +++++++++++++++ 3 files changed, 91 insertions(+), 69 deletions(-)
Update the commit message template with the agreeed format for how to write commit messages in OpenSAF. Add a shell script that can be used to set the default commit message in Mercurial to the commit message template. diff --git a/tools/devel/review/00-README b/tools/devel/review/00-README --- a/tools/devel/review/00-README +++ b/tools/devel/review/00-README @@ -1,79 +1,24 @@ Commit Message Format ===================== -The patch review process heavily relies on properly formatted commit message. -This section will describe how commit message should be formatted and the -relation it has with the patch review process by email. - -A commit message should comply to the following template: - -* First line : 80-chars long one line short description (#ticket). Describe what - the patch is doing logically (not the bug description) -* Second line : Blank -* Third line+ : 80-chars long lines for a more complete description - ------<-----<-----<-----<-----<----- -example: this is a one line short description (#2000) - -This is a more elaborate description that explains your changes and the -original problem and how it got solved. - - * Blah - * Blah - -Signed-off-by: John Doe <john....@example.com> ------<-----<-----<-----<-----<----- - -The first line will be grabbed by the 'hg email' command and added as the -subject of the patch, hence the why it should be short and precise. Note that it -also contains the "area/module/feature" of the changes (i.e. example:). If you -have trouble identifying the unique nature of the patch, your patch is probably -way to long and should be divided in a series. - -The Ticket # in a future integration will be used on the Trac web interface to -correlate tickets and commits. It will also be used by Mercurial hooks to -close/fix tickets automatically if needed. - -The long description gives more details about the patch/changeset. - -The SOB tag is the original patch author. - +The patch review process heavily relies on properly formatted commit messages. +Use the file commit.template in this directory as a template when writing +commit messages. Make sure that your commit message contains all the necessary +parts, i.e. the component name, a short description, the ticket number and +a long description. Default Commit Message Template =============================== -Apparently Mercurial lacks the support of customizing the default commit message -based on a template file somewhere in the repository. +Enter the following set of commands to set up the commit.template as the default +commit message in Mercurial (you need to log out and log in again for the change +to take effect): -The Qct extension can be installed and used in your ~/.hgrc profile to point to -a template file, so that you're nagged every time how to fill the commit -message properly ;) - -For instance under Red Hat/Fedora the package is called 'qct-mercurial' - - % yum install qct-mercurial - % yum install qct - -http://www.selenic.com/mercurial/wiki/index.cgi/QctExtension - -Under './tools/devel/review/commit.template', you'll find a default template that you -can use with the Qct extension. The extension automatically looks for a template -file under `hg root`/.commit.template, a copy is already placed in the OpenSAF -repository for developer that would like to use the Qct extension. - ------<-----<-----<-----<-----<----- -[extensions] -hgext.qct = - -[qct] -signoff = Signed-off-by: John Doe <john....@example.com> ------<-----<-----<-----<-----<----- - -To use the Qct Extension, you'll have to commit your changes using the 'hg -commit-tool | hg qct' command. The tool has neat features, like dynamically -deciding which files will be part of the current commit etc. But it might bug -some developers since it pops up a GUI. - +mkdir ~/bin +cp hgeditor.sh ~/bin +chmod 755 ~/bin/hgeditor.sh +echo "export HGEDITOR=~/bin/hgeditor.sh" >> ~/.bashrc +echo "setenv HGEDITOR ~/bin/hgeditor.sh" >> ~/.cshrc Mercurial Settings Needed for Email Review ========================================== diff --git a/tools/devel/review/commit.template b/tools/devel/review/commit.template --- a/tools/devel/review/commit.template +++ b/tools/devel/review/commit.template @@ -1,6 +1,47 @@ -module: this is a one line short description +component: short_description [#ticket_number] -Ticket #xxx (delete me if none) - -This is a more elaborate description that explains your changes and the -original problem and how it got solved. +long_description +HG: +HG: Enter commit message. Lines beginning with 'HG:' are removed. +HG: An empty message aborts the commit. +HG: +HG: Edit the different parts of the commit message template above as follows: +HG: +HG: component +HG: Concatenation of the "Component" and "Part" fields of the ticket in +HG: the OpenSAF ticket system at SourceForge. The "Part" field is +HG: optional. Write in lower case, with no space or other character +HG: between the component and the part. Follow with a colon and then a +HG: space. +HG: +HG: short_description +HG: A one-line (max 80 characters) description of the changeset, starting +HG: with a verb in present tense (e.g. Add, Fix, Change, ...) +HG: +HG: ticket_number +HG: The ticket number in the OpenSAF ticket system at SourceForge. The +HG: ticket number shall be preceded with a hash sign and surrounded with +HG: square brackets, so that SourceForge recognizes it as a ticket +HG: reference and inserts a hyperlink when displaying the commit message +HG: on a web page. +HG: +HG: long_descrption +HG: The long description shall be a more elaborate description of what +HG: has been changed and why. For defect tickets, the long description +HG: should consist of three parts, separated by blank lines: +HG: +HG: visible_symptoms_of_the_problem +HG: +HG: analysis_of_the_cause +HG: +HG: description_of_the_solution +HG: +HG: The visible_symptoms_of_the_problem should show how the problem +HG: manifests itself, e.g. actual (and verbatim) log messages taken from +HG: a system where the problem occurred. If the problem happens again, it +HG: should be easy to search for the log messages to find the changeset +HG: containing the fix. +HG: +HG: The analysis_of_the_cause shall explain the fault in the program +HG: code. The description_of_the_solution shall explain how the changeset +HG: corrects the fault in the program code. diff --git a/tools/devel/review/hgeditor.sh b/tools/devel/review/hgeditor.sh new file mode 100755 --- /dev/null +++ b/tools/devel/review/hgeditor.sh @@ -0,0 +1,32 @@ +#!/bin/bash + +hgeditor="" +if test -n "$VISUAL" -a -z "$hgeditor"; then + hgeditor=$(type -p "$VISUAL") +fi +if test -n "$EDITOR" -a -z "$hgeditor"; then + hgeditor=$(type -p "$EDITOR") +fi +if test -z "$hgeditor"; then + hgeditor=$(type -p emacs) +fi +if test -z "$hgeditor"; then + hgeditor=$(type -p vi) +fi +if test -z "$hgeditor"; then + echo "Cannot find a suitable editor. Please set the environment variable" + echo "EDITOR" + exit 1 +fi + +template_file=$(hg root)/tools/devel/review/commit.template +if test -s "$template_file"; then + grep -E "^HG:" "$1" >& /dev/null && cp "$template_file" "$1" + test -s "$1" || cp "$template_file" "$1" + "$hgeditor" "$1" + diff -Bw "$template_file" "$1" > /dev/null && exit 1 + sed -i -e "/^\HG:/d" "$1" +else + "$hgeditor" "$1" +fi +grep '[^ \t]' "$1" > /dev/null ------------------------------------------------------------------------------ Managing the Performance of Cloud-Based Applications Take advantage of what the Cloud has to offer - Avoid Common Pitfalls. Read the Whitepaper. http://pubads.g.doubleclick.net/gampad/clk?id=121054471&iu=/4140/ostg.clktrk _______________________________________________ Opensaf-devel mailing list Opensaf-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/opensaf-devel
