Sat Mar 10 01:54:15 2012

Asterisk developer's documentation


commits.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 CommitMessages Guidelines for Commit Messages
00023  *
00024  * \AsteriskTrunkWarning
00025  *
00026  * <hr/>
00027  *
00028  * \section CommitMsgFormatting Commit Message Formatting
00029  *
00030  * The following illustrates the basic outline for commit messages:
00031  *
00032   \verbatim
00033   <One-liner summary of changes>
00034 
00035   <Empty Line> 
00036 
00037   <Verbose description of the changes>
00038 
00039   <Empty Line> 
00040 
00041   <Special Tags>
00042   \endverbatim
00043  *
00044  * Some commit history viewers treat the first line of commit messages as the
00045  * summary for the commit.  So, an effort should be made to format our commit
00046  * messages in that fashion.  The verbose description may contain multiple 
00047  * paragraphs, itemized lists, etc. Always end the first sentence (and any
00048  * subsequent sentences) with punctuation.
00049  *
00050  * Commit messages should be wrapped at 80 %columns.
00051  *
00052  * \note For trivial commits, such as "fix the build", or "fix spelling mistake",
00053  *       the verbose description may not be necessary.
00054  *
00055  * <hr/>
00056  *
00057  * \section CommitMsgTags Special Tags for Commit Messages
00058  *
00059  * \subsection MantisTags Mantis (https://issues.asterisk.org/)
00060  *
00061  * To have a commit noted in an issue, use a tag of the form: 
00062  * \arg (issue #1234)
00063  *
00064  * To have a commit automatically close an issue, use a tag of the form:
00065  * \arg (closes issue #1234)
00066  *
00067  * When making a commit for a mantis issue, it is easiest to use the
00068  * provided commit %message template functionality.  It will format the
00069  * special tags appropriately, and will also include information about who
00070  * reported the issue, which patches are being applied, and who did testing.
00071  * 
00072  * Assuming that you have bug marshal access (and if you have commit access,
00073  * it is pretty safe to assume that you do), you will find the commit %message
00074  * template section directly below the issue details section and above the
00075  * issue relationships section.  You will have to click the '+' next to
00076  * "Commit message template" to make the contents of the section visible.
00077  *
00078  * Here is an example of what the template will generate for you:
00079  *
00080   \verbatim
00081   (closes issue #1234)
00082   Reported by: SomeGuy
00083   Patches:
00084        fix_bug_1234.diff uploaded by SomeDeveloper (license 5678)
00085   \endverbatim
00086  *
00087  * If the patch being committed was written by the person doing the commit,
00088  * and is not available to reference as an upload to the issue, there is no
00089  * need to include something like "fixed by me", as that will be the default
00090  * assumption when a specific patch is not referenced.
00091  *
00092  * \subsection ReviewBoardTags Review Board (https://reviewboard.asterisk.org/)
00093  *
00094  * To have a commit set a review request as submitted, include the full URL
00095  * to the review request.  For example:
00096  * \arg Review: %https://reviewboard.asterisk.org/r/95/
00097  *
00098  * \note The trailing slash in the review URL is required.
00099  *
00100  * <hr/>
00101  *
00102  * \section CommitMsgSvnmerge Commit Messages with svnmerge
00103  *
00104  * When using the svnmerge tool for merging changes between branches, use the
00105  * commit %message generated by svnmerge.  The '-f' option to svnmerge allows
00106  * you to specify a file for svnmerge to write out a commit %message to.  The
00107  * '-F' option to svn commit allows you to specify a file that contains the
00108  * commit %message.
00109  *
00110  * If you are using the expect script wrappers for svnmerge from repotools,
00111  * a commit %message is automatically placed in the file '../merge.msg'.
00112  *
00113  * For more detailed information about working with branches and merging,
00114  * see the following page on %asterisk.org:
00115  * \arg http://www.asterisk.org/developers/svn-branching-merging
00116  */
00117 
00118 

Generated on Sat Mar 10 01:54:15 2012 for Asterisk - The Open Source Telephony Project by  doxygen 1.4.7