Thu Oct 11 06:33:55 2012

Asterisk developer's documentation


reviewboard.h

Go to the documentation of this file.
00001 /*
00002 * Asterisk -- An open source telephony toolkit.
00003 *
00004 * Copyright (C) 1999 - 2009, Digium, Inc.
00005 *
00006 * See http://www.asterisk.org for more information about
00007 * the Asterisk project. Please do not directly contact
00008 * any of the maintainers of this project for assistance;
00009 * the project provides a web site, mailing lists and IRC
00010 * channels for your use.
00011 *
00012 * This program is free software, distributed under the terms of
00013 * the GNU General Public License Version 2. See the LICENSE file
00014 * at the top of the source tree.
00015 */
00016 
00017 /*!
00018 * \file
00019 */
00020 
00021 /*!
00022  * \page Reviewboard Reviewboard Usage and Guidelines
00023  *
00024  * \AsteriskTrunkWarning
00025  *
00026  * <hr>
00027  *
00028  * \section ReviewboardGuidelines Usage Guidelines
00029  *
00030  * Mantis (https://issues.asterisk.org) and Reviewboard (https://reviewboard.asterisk.org)
00031  * are both utilities that the Asterisk development community uses to help
00032  * track and review code being written for Asterisk.  Since both systems
00033  * are used for posting patches, it is worth discussing when it is appropriate
00034  * to use reviewboard and when not.
00035  *
00036  * Here are the situations in which it is appropriate to post code to reviewboard:
00037  *  - A committer has a patch that they would like to get some feedback on before
00038  *    merging into one of the main branches.
00039  *  - A committer or bug marshal has requested a contributor to post their patch
00040  *    from Mantis on reviewboard to aid in the review process.  This typically
00041  *    happens with complex code contributions where reviewboard can help aid in
00042  *    providing feedback.
00043  *
00044  * We do encourage all interested parties to participate in the review process.
00045  * However, aside from the cases mentioned above, we prefer that all code
00046  * submissions first go through Mantis.
00047  *
00048  * \note It is acceptable for a committer to post patches to reviewboard before
00049  * they are complete to get some feedback on the approach being taken.  However,
00050  * if the code is not yet ready to be merged, it \b must be documented as such.
00051  * A review request with a patch proposed for merging should have documented
00052  * testing and should not have blatant coding guidelines violations.  Lack of
00053  * these things is careless and shows disrespect for those reviewing your code.
00054  *
00055  * <hr>
00056  *
00057  * \section ReviewboardPosting Posting Code to Reviewboard
00058  *
00059  * \subsection postreview Using post-review
00060  *
00061  * The easiest way to post a patch to reviewboard is by using the
00062  * post-review tool.  We have post-review in our repotools svn repository.
00063  *
00064  * \verbatim
00065  * $ svn co http://svn.digium.com/svn/repotools
00066  * \endverbatim
00067  *
00068  * Essentially, post-review is a script that will take the output of "svn
00069  * diff" and create a review request out of it for you.  So, once you have
00070  * a working copy with the changes you expect in the output of "svn diff",
00071  * you just run the following command:
00072  *
00073  * \verbatim
00074  * $ post-review
00075  * \endverbatim
00076  * 
00077  * If it complains about not knowing which reviewboard server to use, add
00078  * the server option:
00079  * 
00080  * \verbatim
00081  * $ post-review --server=https://reviewboard.asterisk.org
00082  * \endverbatim
00083  *
00084  * \subsection postreviewnewfiles Dealing with New Files
00085  * 
00086  * I have one final note about an oddity with using post-review.  If you
00087  * maintain your code in a team branch, and the new code includes new
00088  * files, there are some additional steps you must take to get post-review
00089  * to behave properly.
00090  * 
00091  * You would start by getting your changes applied to a trunk working copy:
00092  * 
00093  * \verbatim
00094  * $ cd .../trunk
00095  * \endverbatim
00096  * 
00097  * Then, apply the changes from your branch:
00098  * 
00099  * \verbatim
00100  * $ svn merge .../trunk .../team/group/my_new_code
00101  * \endverbatim
00102  * 
00103  * Now, the code is merged into your working copy.  However, for a new
00104  * file, subversion treats it as a copy of existing content and not new
00105  * content, so new files don't show up in "svn diff" at this point.  To get
00106  * it to show up in the diff, use the following commands so svn treats it
00107  * as new content and publishes it in the diff:
00108  * 
00109  * \verbatim
00110  * $ svn revert my_new_file.c
00111  * $ svn add my_new_file.c
00112  * \endverbatim
00113  * 
00114  * Now, it should work, and you can run "post-review" as usual.
00115  *
00116  * \subsection postreviewupdate Updating Patch on Existing Review Request
00117  *
00118  * Most of the time, a patch on reviewboard will require multiple iterations
00119  * before other sign off on it being ready to be merged.  To update the diff
00120  * for an existing review request, you can use post-review and the -r option.
00121  * Apply the current version of the diff to a working copy as described above,
00122  * and then run the following command:
00123  * 
00124  * \verbatim
00125  * $ post-review -r <review request number>
00126  * \endverbatim
00127  */

Generated on Thu Oct 11 06:33:55 2012 for Asterisk - The Open Source Telephony Project by  doxygen 1.5.6