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