[svn-commits] russell: branch russell/project_docs r165320 - /team/russell/project_docs/inc...

[SVN commits to the Digium repositories]

Author: russell
Date: Wed Dec 17 15:19:28 2008
New Revision: 165320

URL: http://svn.digium.com/view/asterisk?view=rev&rev=165320
Log:
commit patch for commit message formatting info ... about to post to reviewboard

Modified:
    team/russell/project_docs/include/asterisk/doxyref.h

Modified: team/russell/project_docs/include/asterisk/doxyref.h
URL: http://svn.digium.com/view/asterisk/team/russell/project_docs/include/asterisk/doxyref.h?view=diff&rev=165320&r1=165319&r2=165320
==============================================================================
--- team/russell/project_docs/include/asterisk/doxyref.h (original)
+++ team/russell/project_docs/include/asterisk/doxyref.h Wed Dec 17 15:19:28 2008
@@ -31,6 +31,7 @@
  *
  * \section devpolicy Development and Release Policies
  * \arg \ref CodeGuide : The must-read document for all developers
+ * \arg \ref CommitMessages : Information on formatting and special tags for commit messages
  * \arg \ref ReleaseStatus : The current support level for various Asterisk releases
  * \arg \ref ReleasePolicies : Asterisk Release and Commit Policies
  * \arg \ref AstCREDITS : A Thank You to contributors (unfortunately out of date)
@@ -334,6 +335,82 @@
  * This file is in the /doc directory in your Asterisk source tree.
  * Make sure to stay up to date with the latest guidelines.
  * \verbinclude CODING-GUIDELINES
+ */
+
+/*!
+ * \page CommitMessages Guidelines for Commit Messages
+ *
+ * \AsteriskTrunkWarning
+ *
+ * <hr/>
+ *
+ * \section CommitMsgFormatting Commit Message Formatting
+ *
+ * The following illustrates the basic outline for commit messages:
+ *
+  \verbatim
+  <One-liner summary of changes>
+ 
+  <Verbose description of the changes>
+
+  <Special Tags>
+  \endverbatim
+ *
+ * Some commit history viewers treat the first line of commit messages as the
+ * summary for the commit.  So, an effort should be made to format our commit
+ * messages in that fashion.  The verbose description may contain multiple 
+ * paragraphs, itemized lists, etc.
+ *
+ * Commit messages should be wrapped at 80 %columns.
+ *
+ * <hr/>
+ *
+ * \section CommitMsgTags Special Tags for Commit Messages
+ *
+ * \subsection MantisTags Mantis (http://bugs.digium.com/)
+ *
+ * To have a commit noted in an issue, use a tag of the form: 
+ * \arg (issue #1234)
+ *
+ * To have a commit automatically close an issue, use a of of the form:
+ * \arg (closes issue #1234)
+ *
+ * When making a commit for a mantis issue, it is easiest to use the
+ * provided commit %message template functionality.  It will format the
+ * special tags appropriately, and will also include information about who
+ * reported the issue, which patches are being applied, and who did testing.
+ * For example:
+ *
+  \verbatim
+  (closes issue #1234)
+  Reported by: SomeGuy
+  Patches:
+       patch_for_stuff.diff uploaded by SomeGuy (license 5678)
+  \endverbatim
+ *
+ * If the patch being committed was written by the person doing the commit,
+ * and is not available to reference as an upload to the issue, there is no
+ * need to include something like "fixed by me", as that will be the default
+ * assumption when a specific patch is not referenced.
+ *
+ * \subsection ReviewBoardTags Review Board (http://reviewboard.digium.com/)
+ *
+ * To have a commit set a review request as submitted, include the full URL
+ * to the review request.  For example:
+ * \arg Review: http://reviewboard.digium.com/r/95/
+ *
+ * <hr/>
+ *
+ * \section CommitMsgSvnmerge Commit Messages with svnmerge
+ *
+ * When using the svnmerge tool for merging changes between branches, use the
+ * commit %message generated by svnmerge.  The '-f' option to svnmerge allows
+ * you to specify a file for svnmerge to write out a commit %message to.  The
+ * '-F' option to svn commit allows you to specify a file that contains the
+ * commit %message.
+ *
+ * If you are using the expect script wrappers for svnmerge from repotools,
+ * a commit %message is automatically placed in the file '../merge.msg'.
  */
 
 /*!