7f39c6e8e0b169c53a740609db15ce8162b70131
[asterisk/asterisk.git] / include / asterisk / doxygen / commits.h
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 1999 - 2009, Digium, Inc.
5  *
6  * See http://www.asterisk.org for more information about
7  * the Asterisk project. Please do not directly contact
8  * any of the maintainers of this project for assistance;
9  * the project provides a web site, mailing lists and IRC
10  * channels for your use.
11  *
12  * This program is free software, distributed under the terms of
13  * the GNU General Public License Version 2. See the LICENSE file
14  * at the top of the source tree.
15  */
16
17 /*!
18  * \file
19  */
20
21 /*!
22  * \page CommitMessages Guidelines for Commit Messages
23  *
24  * \AsteriskTrunkWarning
25  *
26  * <hr>
27  *
28  * \section CommitMsgFormatting Commit Message Formatting
29  *
30  * The following illustrates the basic outline for commit messages:
31  *
32  * \verbatim
33  * <One-liner summary of changes>
34  *
35  * <Empty Line> 
36  *
37  * <Verbose description of the changes>
38  *
39  * <Empty Line> 
40  *
41  * <Special Tags>
42  * \endverbatim
43  *
44  * Some commit history viewers treat the first line of commit messages as the
45  * summary for the commit.  So, an effort should be made to format our commit
46  * messages in that fashion.  The verbose description may contain multiple 
47  * paragraphs, itemized lists, etc. Always end the first sentence (and any
48  * subsequent sentences) with punctuation.
49  *
50  * Commit messages should be wrapped at 80 %columns.
51  *
52  * \note For trivial commits, such as "fix the build", or "fix spelling mistake",
53  *       the verbose description may not be necessary.
54  *
55  * <hr>
56  *
57  * \section CommitMsgTags Special Tags for Commit Messages
58  *
59  * \subsection MantisTags Mantis (https://issues.asterisk.org/)
60  *
61  * To have a commit noted in an issue, use a tag of the form: 
62  * \arg (issue #1234)
63  *
64  * To have a commit automatically close an issue, use a tag of the form:
65  * \arg (closes issue #1234)
66  *
67  * When making a commit for a mantis issue, it is easiest to use the
68  * provided commit %message template functionality.  It will format the
69  * special tags appropriately, and will also include information about who
70  * reported the issue, which patches are being applied, and who did testing.
71  * 
72  * Assuming that you have bug marshal access (and if you have commit access,
73  * it is pretty safe to assume that you do), you will find the commit %message
74  * template section directly below the issue details section and above the
75  * issue relationships section.  You will have to click the '+' next to
76  * "Commit message template" to make the contents of the section visible.
77  *
78  * Here is an example of what the template will generate for you:
79  *
80  * \verbatim
81  * (closes issue #1234)
82  * Reported by: SomeGuy
83  * Patches:
84  *      fix_bug_1234.diff uploaded by SomeDeveloper (license 5678)
85  * \endverbatim
86  *
87  * If the patch being committed was written by the person doing the commit,
88  * and is not available to reference as an upload to the issue, there is no
89  * need to include something like "fixed by me", as that will be the default
90  * assumption when a specific patch is not referenced.
91  *
92  * \subsection ReviewBoardTags Review Board (https://reviewboard.asterisk.org/)
93  *
94  * To have a commit set a review request as submitted, include the full URL
95  * to the review request.  For example:
96  * \arg Review: %https://reviewboard.asterisk.org/r/95/
97  *
98  * \note The trailing slash in the review URL is required.
99  *
100  * <hr>
101  *
102  * \section CommitMsgSvnmerge Commit Messages with svnmerge
103  *
104  * When using the svnmerge tool for merging changes between branches, use the
105  * commit %message generated by svnmerge.  The '-f' option to svnmerge allows
106  * you to specify a file for svnmerge to write out a commit %message to.  The
107  * '-F' option to svn commit allows you to specify a file that contains the
108  * commit %message.
109  *
110  * If you are using the expect script wrappers for svnmerge from repotools,
111  * a commit %message is automatically placed in the file '../merge.msg'.
112  *
113  * For more detailed information about working with branches and merging,
114  * see the following page on %asterisk.org:
115  * \arg http://www.asterisk.org/developers/svn-branching-merging
116  */
117
118