httpd-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From poir...@apache.org
Subject svn commit: r911490 - /httpd/site/trunk/xdocs/dev/guidelines.xml
Date Thu, 18 Feb 2010 16:59:59 GMT
Author: poirier
Date: Thu Feb 18 16:59:59 2010
New Revision: 911490

URL: http://svn.apache.org/viewvc?rev=911490&view=rev
Log:
Add some guidelines on documenting changes in Subversion logs
and CHANGES files.

Modified:
    httpd/site/trunk/xdocs/dev/guidelines.xml

Modified: httpd/site/trunk/xdocs/dev/guidelines.xml
URL: http://svn.apache.org/viewvc/httpd/site/trunk/xdocs/dev/guidelines.xml?rev=911490&r1=911489&r2=911490&view=diff
==============================================================================
--- httpd/site/trunk/xdocs/dev/guidelines.xml [utf-8] (original)
+++ httpd/site/trunk/xdocs/dev/guidelines.xml [utf-8] Thu Feb 18 16:59:59 2010
@@ -300,6 +300,118 @@
 
 </section>
 
+<section id="changelogs"><title>CHANGES file and Subversion logs</title>
+<p>Many code changes should be noted in the CHANGES file, and
+all should be documented in Subversion commit messages.
+Often the text of the Subversion log and the CHANGES entry are the same, but
+the distinct requirements sometimes result in different information.</p>
+
+<section><title>Subversion log</title>
+<p>The Subversion commit log message contains any information needed by
+<ul>
+<li>fellow developers or other people researching source code changes/fixes</li>
+<li>end users (at least point out what the implications are for end
+users; it doesn't have to be in the most user friendly wording)</li>
+</ul>
+</p>
+
+<p>If the code change was provided by a non-committer, attribute it
+using Submitted-by.  If the change was committed verbatim, identify
+the committer(s) who reviewed it with Reviewed-by.  If the change was
+committed with modifications, use the appropriate wording to document
+that, perhaps "committed with changes" if the person making the commit
+made the changes, or "committed with contributions from xxxx" if
+others made contributions to the code committed.</p>
+
+<p>Example log message:
+
+<pre>
+Check the return code from parsing the content length, to avoid a
+crash if requests contain an invalid content length.
+
+PR: 99999
+Submitted by: Jane Doe &lt;janedoe example.com&gt;
+Reviewed by: susiecommitter
+</pre>
+</p>
+
+<p>Commit messages can be minimal when making routine updates to STATUS,
+for example to propose a backport or vote.</p>
+
+</section>
+
+<section><title>CHANGES</title>
+<p>CHANGES is the subset of the information that end users need to see
+when they upgrade from one release to the next:<ul>
+<li>what can I now do that I couldn't do before</li>
+<li>what problems that we anticipate a user could have suffered from are now fixed</li>
+<li>all security fixes included, with CVE number.  (If not available at
+the time of the commit, add later.)</li>
+</ul></p>
+
+<p>The usability of CHANGES for end users decreases as information of use
+to few individuals, or which doesn't pertain to evaluating the new
+release, is added.  Specifically:<ul>
+<li>Fixes for bugs introduced after the last release don't belong in CHANGES.</li>
+<li>Fixes for bugs that we don't expect anybody noticed don't belong in
+CHANGES.  (Bend the rule a little for outside contributions, as the
+submitter may need to see their name in lights as reward for their
+efforts, which typically were undertaken with no guarantee that any
+committer would take interest.)</li>
+<li>Documentation fixes, whether for end users or developers, don't
+belong in CHANGES.</li></ul></p>
+
+<p>CHANGES applies to changes even between alpha releases, so backporting
+a change from trunk to a stable release does not generally require removing
+the change from the CHANGES file in trunk.</p>
+
+<p>The attribution for the change is anyone responsible for the code changes.</p>
+</section>
+
+<section><title>Formatting</title>
+<p>Identify non-committers by name, and their email in obfuscated
+form if available.  The obfuscation is done by replacing "@" with a 
+space and adding "&lt;" and ">" around the address.  For example,
+change <tt>user@example.com</tt> to <tt>&lt;user example.com&gt;</tt>.
+</p>
+
+<p>Identify committers with their Apache userid, e.g. <tt>xyz</tt>
+(no domain name needed).  </p>
+
+<p>If the change is related to a bugzilla issue, include the PR number
+in the log in the format:<pre>
+PR nnnnn
+</pre></p>
+
+<p>Security-related changes should start like this:<pre>
+  *) SECURITY: CVE-YYYY-NNNN (cve.mitre.org)
+  xxxxxxxxxx
+</pre></p>
+
+<p>Most changes are inserted at the top of the CHANGES file.  However,
+security-related changes should always be at the top of the list of changes
+for the relevant release, so if there are unreleased security changes
+at the top of the file, insert other changes below them.</p>
+
+<p>Example CHANGES entries:
+
+<pre>
+  *) SECURITY: CVE-2009-3095 (cve.mitre.org)
+     mod_proxy_ftp: sanity check authn credentials.
+     [Stefan Fritsch &lt;sf fritsch.de>, Joe Orton]
+
+  *) Replace AcceptMutex, LockFile, RewriteLock, SSLMutex, SSLStaplingMutex,
+     and WatchdogMutexPath with a single Mutex directive.  Add APIs to
+     simplify setup and user customization of APR proc and global mutexes.  
+     (See util_mutex.h.)  Build-time setting DEFAULT_LOCKFILE is no longer
+     respected; set DEFAULT_REL_RUNTIMEDIR instead.  [Jeff Trawick]
+</pre>
+</p>
+
+</section>
+
+</section>
+
 <section id="patch"><title>Patch Format</title>
 <p>When a specific change to the software is proposed for discussion or
 voting on the mailing list, it should be presented in the form of input 



Mime
View raw message