Introduce commit message formatting guidelines.
[asterisk/asterisk.git] / include / asterisk / doxyref.h
index 7ae7ce5..c3decfa 100644 (file)
@@ -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)
  * \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.
+ *
+ * \note For trivial commits, such as "fix the build", or "fix spelling mistake",
+ *       the verbose description may not be necessary.
+ *
+ * <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 tag 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.
+ * 
+ * Assuming that you have bug marshal access (and if you have commit access,
+ * it is pretty safe to assume that you do), you will find the commit %message
+ * template section directly below the issue details section and above the
+ * issue relationships section.  You will have to click the '+' next to
+ * "Commit message template" to make the contents of the section visible.
+ *
+ * Here is an example of what the template will generate for you:
+ *
+  \verbatim
+  (closes issue #1234)
+  Reported by: SomeGuy
+  Patches:
+       fix_bug_1234.diff uploaded by SomeDeveloper (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'.
+ *
+ * For more detailed information about working with branches and merging,
+ * see the following page on %asterisk.org:
+ * \arg http://www.asterisk.org/developers/svn-branching-merging
+ */
+
 /*! 
  * \page AstAPI Asterisk API
  * \section Asteriskapi Asterisk API