diff options
| -rw-r--r-- | include/asterisk/doxyref.h | 91 |
1 files changed, 91 insertions, 0 deletions
diff --git a/include/asterisk/doxyref.h b/include/asterisk/doxyref.h index 7ae7ce5e6..c3decfa9b 100644 --- a/include/asterisk/doxyref.h +++ b/include/asterisk/doxyref.h @@ -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) @@ -336,6 +337,96 @@ * \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 |