svn commit: r911491 - /httpd/site/trunk/docs/dev/guidelines.html

[po...@apache.org]

Author: poirier
Date: Thu Feb 18 17:00:14 2010
New Revision: 911491

URL: http://svn.apache.org/viewvc?rev=911491&view=rev
Log:
Transform

Modified:
    httpd/site/trunk/docs/dev/guidelines.html

Modified: httpd/site/trunk/docs/dev/guidelines.html
URL: http://svn.apache.org/viewvc/httpd/site/trunk/docs/dev/guidelines.html?rev=911491&r1=911490&r2=911491&view=diff
==============================================================================
--- httpd/site/trunk/docs/dev/guidelines.html [utf-8] (original)
+++ httpd/site/trunk/docs/dev/guidelines.html [utf-8] Thu Feb 18 17:00:14 2010
@@ -399,6 +399,144 @@
  <tr>
  <td bgcolor="#525D76">
   <font color="#ffffff" face="arial,helvetica,sanserif">
+   <a name="changelogs"><strong>CHANGES file and Subversion logs</strong></a>
+  </font>
+ </td>
+ </tr>
+ <tr><td>
+  <blockquote>
+<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>
+<table border="0" cellspacing="0" cellpadding="2" width="100%">
+ <tr>
+ <td bgcolor="#828DA6">
+  <font color="#ffffff" face="arial,helvetica,sanserif">
+   <strong>Subversion log</strong>
+  </font>
+ </td>
+ </tr>
+ <tr><td>
+  <blockquote>
+<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>
+  </blockquote>
+ </td></tr>
+</table>
+<table border="0" cellspacing="0" cellpadding="2" width="100%">
+ <tr>
+ <td bgcolor="#828DA6">
+  <font color="#ffffff" face="arial,helvetica,sanserif">
+   <strong>CHANGES</strong>
+  </font>
+ </td>
+ </tr>
+ <tr><td>
+  <blockquote>
+<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>
+  </blockquote>
+ </td></tr>
+</table>
+<table border="0" cellspacing="0" cellpadding="2" width="100%">
+ <tr>
+ <td bgcolor="#828DA6">
+  <font color="#ffffff" face="arial,helvetica,sanserif">
+   <strong>Formatting</strong>
+  </font>
+ </td>
+ </tr>
+ <tr><td>
+  <blockquote>
+<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 "&gt;" 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&gt;, 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>
+  </blockquote>
+ </td></tr>
+</table>
+  </blockquote>
+ </td></tr>
+</table>
+           <table border="0" cellspacing="0" cellpadding="2" width="100%">
+ <tr>
+ <td bgcolor="#525D76">
+  <font color="#ffffff" face="arial,helvetica,sanserif">
    <a name="patch"><strong>Patch Format</strong></a>
   </font>
  </td>