res_rtp_asterisk.c: Fix rtp source address learning for broken clients
[asterisk/asterisk.git] / include / asterisk / doxygen / reviewboard.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 Reviewboard Reviewboard Usage and Guidelines
23  *
24  * <hr>
25  *
26  * \section ReviewboardGuidelines Usage Guidelines
27  *
28  * Mantis (https://issues.asterisk.org) and Reviewboard (https://reviewboard.asterisk.org)
29  * are both utilities that the Asterisk development community uses to help
30  * track and review code being written for Asterisk.  Since both systems
31  * are used for posting patches, it is worth discussing when it is appropriate
32  * to use reviewboard and when not.
33  *
34  * Here are the situations in which it is appropriate to post code to reviewboard:
35  *  - A committer has a patch that they would like to get some feedback on before
36  *    merging into one of the main branches.
37  *  - A committer or bug marshal has requested a contributor to post their patch
38  *    from Mantis on reviewboard to aid in the review process.  This typically
39  *    happens with complex code contributions where reviewboard can help aid in
40  *    providing feedback.
41  *
42  * We do encourage all interested parties to participate in the review process.
43  * However, aside from the cases mentioned above, we prefer that all code
44  * submissions first go through Mantis.
45  *
46  * \note It is acceptable for a committer to post patches to reviewboard before
47  * they are complete to get some feedback on the approach being taken.  However,
48  * if the code is not yet ready to be merged, it \b must be documented as such.
49  * A review request with a patch proposed for merging should have documented
50  * testing and should not have blatant coding guidelines violations.  Lack of
51  * these things is careless and shows disrespect for those reviewing your code.
52  *
53  * <hr>
54  *
55  * \section ReviewboardPosting Posting Code to Reviewboard
56  *
57  * \subsection postreview Using post-review
58  *
59  * The easiest way to post a patch to reviewboard is by using the
60  * post-review tool.  We have post-review in our repotools svn repository.
61  *
62  * \verbatim
63  * $ svn co http://svn.digium.com/svn/repotools
64  * \endverbatim
65  *
66  * Essentially, post-review is a script that will take the output of "svn
67  * diff" and create a review request out of it for you.  So, once you have
68  * a working copy with the changes you expect in the output of "svn diff",
69  * you just run the following command:
70  *
71  * \verbatim
72  * $ post-review
73  * \endverbatim
74  * 
75  * If it complains about not knowing which reviewboard server to use, add
76  * the server option:
77  * 
78  * \verbatim
79  * $ post-review --server=https://reviewboard.asterisk.org
80  * \endverbatim
81  *
82  * \subsection postreviewnewfiles Dealing with New Files
83  * 
84  * I have one final note about an oddity with using post-review.  If you
85  * maintain your code in a team branch, and the new code includes new
86  * files, there are some additional steps you must take to get post-review
87  * to behave properly.
88  * 
89  * You would start by getting your changes applied to a trunk working copy:
90  * 
91  * \verbatim
92  * $ cd .../trunk
93  * \endverbatim
94  * 
95  * Then, apply the changes from your branch:
96  * 
97  * \verbatim
98  * $ svn merge .../trunk .../team/group/my_new_code
99  * \endverbatim
100  * 
101  * Now, the code is merged into your working copy.  However, for a new
102  * file, subversion treats it as a copy of existing content and not new
103  * content, so new files don't show up in "svn diff" at this point.  To get
104  * it to show up in the diff, use the following commands so svn treats it
105  * as new content and publishes it in the diff:
106  * 
107  * \verbatim
108  * $ svn revert my_new_file.c
109  * $ svn add my_new_file.c
110  * \endverbatim
111  * 
112  * Now, it should work, and you can run "post-review" as usual.
113  *
114  * \subsection postreviewupdate Updating Patch on Existing Review Request
115  *
116  * Most of the time, a patch on reviewboard will require multiple iterations
117  * before other sign off on it being ready to be merged.  To update the diff
118  * for an existing review request, you can use post-review and the -r option.
119  * Apply the current version of the diff to a working copy as described above,
120  * and then run the following command:
121  * 
122  * \verbatim
123  * $ post-review -r <review request number>
124  * \endverbatim
125  */