Update references to bugs.digium.com and reviewboard.digium.com to the new URLs.
[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   <Verbose description of the changes>
36
37   <Special Tags>
38   \endverbatim
39  *
40  * Some commit history viewers treat the first line of commit messages as the
41  * summary for the commit.  So, an effort should be made to format our commit
42  * messages in that fashion.  The verbose description may contain multiple 
43  * paragraphs, itemized lists, etc. Always end the first sentence (and any
44  * subsequent sentences) with punctuation.
45  *
46  * Commit messages should be wrapped at 80 %columns.
47  *
48  * \note For trivial commits, such as "fix the build", or "fix spelling mistake",
49  *       the verbose description may not be necessary.
50  *
51  * <hr/>
52  *
53  * \section CommitMsgTags Special Tags for Commit Messages
54  *
55  * \subsection MantisTags Mantis (https://issues.asterisk.org/)
56  *
57  * To have a commit noted in an issue, use a tag of the form: 
58  * \arg (issue #1234)
59  *
60  * To have a commit automatically close an issue, use a tag of the form:
61  * \arg (closes issue #1234)
62  *
63  * When making a commit for a mantis issue, it is easiest to use the
64  * provided commit %message template functionality.  It will format the
65  * special tags appropriately, and will also include information about who
66  * reported the issue, which patches are being applied, and who did testing.
67  * 
68  * Assuming that you have bug marshal access (and if you have commit access,
69  * it is pretty safe to assume that you do), you will find the commit %message
70  * template section directly below the issue details section and above the
71  * issue relationships section.  You will have to click the '+' next to
72  * "Commit message template" to make the contents of the section visible.
73  *
74  * Here is an example of what the template will generate for you:
75  *
76   \verbatim
77   (closes issue #1234)
78   Reported by: SomeGuy
79   Patches:
80        fix_bug_1234.diff uploaded by SomeDeveloper (license 5678)
81   \endverbatim
82  *
83  * If the patch being committed was written by the person doing the commit,
84  * and is not available to reference as an upload to the issue, there is no
85  * need to include something like "fixed by me", as that will be the default
86  * assumption when a specific patch is not referenced.
87  *
88  * \subsection ReviewBoardTags Review Board (https://reviewboard.asterisk.org/)
89  *
90  * To have a commit set a review request as submitted, include the full URL
91  * to the review request.  For example:
92  * \arg Review: %https://reviewboard.asterisk.org/r/95/
93  *
94  * \note The trailing slash in the review URL is required.
95  *
96  * <hr/>
97  *
98  * \section CommitMsgSvnmerge Commit Messages with svnmerge
99  *
100  * When using the svnmerge tool for merging changes between branches, use the
101  * commit %message generated by svnmerge.  The '-f' option to svnmerge allows
102  * you to specify a file for svnmerge to write out a commit %message to.  The
103  * '-F' option to svn commit allows you to specify a file that contains the
104  * commit %message.
105  *
106  * If you are using the expect script wrappers for svnmerge from repotools,
107  * a commit %message is automatically placed in the file '../merge.msg'.
108  *
109  * For more detailed information about working with branches and merging,
110  * see the following page on %asterisk.org:
111  * \arg http://www.asterisk.org/developers/svn-branching-merging
112  */
113
114