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