00001 /* 00002 * Asterisk -- An open source telephony toolkit. 00003 * 00004 * Copyright (C) 1999 - 2009, Digium, Inc. 00005 * 00006 * See http://www.asterisk.org for more information about 00007 * the Asterisk project. Please do not directly contact 00008 * any of the maintainers of this project for assistance; 00009 * the project provides a web site, mailing lists and IRC 00010 * channels for your use. 00011 * 00012 * This program is free software, distributed under the terms of 00013 * the GNU General Public License Version 2. See the LICENSE file 00014 * at the top of the source tree. 00015 */ 00016 00017 /*! 00018 * \file 00019 */ 00020 00021 /*! 00022 * \page CommitMessages Guidelines for Commit Messages 00023 * 00024 * \AsteriskTrunkWarning 00025 * 00026 * <hr/> 00027 * 00028 * \section CommitMsgFormatting Commit Message Formatting 00029 * 00030 * The following illustrates the basic outline for commit messages: 00031 * 00032 \verbatim 00033 <One-liner summary of changes> 00034 00035 <Empty Line> 00036 00037 <Verbose description of the changes> 00038 00039 <Empty Line> 00040 00041 <Special Tags> 00042 \endverbatim 00043 * 00044 * Some commit history viewers treat the first line of commit messages as the 00045 * summary for the commit. So, an effort should be made to format our commit 00046 * messages in that fashion. The verbose description may contain multiple 00047 * paragraphs, itemized lists, etc. Always end the first sentence (and any 00048 * subsequent sentences) with punctuation. 00049 * 00050 * Commit messages should be wrapped at 80 %columns. 00051 * 00052 * \note For trivial commits, such as "fix the build", or "fix spelling mistake", 00053 * the verbose description may not be necessary. 00054 * 00055 * <hr/> 00056 * 00057 * \section CommitMsgTags Special Tags for Commit Messages 00058 * 00059 * \subsection MantisTags Mantis (https://issues.asterisk.org/) 00060 * 00061 * To have a commit noted in an issue, use a tag of the form: 00062 * \arg (issue #1234) 00063 * 00064 * To have a commit automatically close an issue, use a tag of the form: 00065 * \arg (closes issue #1234) 00066 * 00067 * When making a commit for a mantis issue, it is easiest to use the 00068 * provided commit %message template functionality. It will format the 00069 * special tags appropriately, and will also include information about who 00070 * reported the issue, which patches are being applied, and who did testing. 00071 * 00072 * Assuming that you have bug marshal access (and if you have commit access, 00073 * it is pretty safe to assume that you do), you will find the commit %message 00074 * template section directly below the issue details section and above the 00075 * issue relationships section. You will have to click the '+' next to 00076 * "Commit message template" to make the contents of the section visible. 00077 * 00078 * Here is an example of what the template will generate for you: 00079 * 00080 \verbatim 00081 (closes issue #1234) 00082 Reported by: SomeGuy 00083 Patches: 00084 fix_bug_1234.diff uploaded by SomeDeveloper (license 5678) 00085 \endverbatim 00086 * 00087 * If the patch being committed was written by the person doing the commit, 00088 * and is not available to reference as an upload to the issue, there is no 00089 * need to include something like "fixed by me", as that will be the default 00090 * assumption when a specific patch is not referenced. 00091 * 00092 * \subsection ReviewBoardTags Review Board (https://reviewboard.asterisk.org/) 00093 * 00094 * To have a commit set a review request as submitted, include the full URL 00095 * to the review request. For example: 00096 * \arg Review: %https://reviewboard.asterisk.org/r/95/ 00097 * 00098 * \note The trailing slash in the review URL is required. 00099 * 00100 * <hr/> 00101 * 00102 * \section CommitMsgSvnmerge Commit Messages with svnmerge 00103 * 00104 * When using the svnmerge tool for merging changes between branches, use the 00105 * commit %message generated by svnmerge. The '-f' option to svnmerge allows 00106 * you to specify a file for svnmerge to write out a commit %message to. The 00107 * '-F' option to svn commit allows you to specify a file that contains the 00108 * commit %message. 00109 * 00110 * If you are using the expect script wrappers for svnmerge from repotools, 00111 * a commit %message is automatically placed in the file '../merge.msg'. 00112 * 00113 * For more detailed information about working with branches and merging, 00114 * see the following page on %asterisk.org: 00115 * \arg http://www.asterisk.org/developers/svn-branching-merging 00116 */ 00117 00118