Return-Path: Delivered-To: apmail-httpd-cvs-archive@www.apache.org Received: (qmail 94450 invoked from network); 18 Feb 2010 17:00:44 -0000 Received: from hermes.apache.org (HELO mail.apache.org) (140.211.11.3) by minotaur.apache.org with SMTP; 18 Feb 2010 17:00:44 -0000 Received: (qmail 56157 invoked by uid 500); 18 Feb 2010 17:00:44 -0000 Delivered-To: apmail-httpd-cvs-archive@httpd.apache.org Received: (qmail 56063 invoked by uid 500); 18 Feb 2010 17:00:44 -0000 Mailing-List: contact cvs-help@httpd.apache.org; run by ezmlm Precedence: bulk Reply-To: dev@httpd.apache.org list-help: list-unsubscribe: List-Post: List-Id: Delivered-To: mailing list cvs@httpd.apache.org Received: (qmail 56054 invoked by uid 99); 18 Feb 2010 17:00:44 -0000 Received: from nike.apache.org (HELO nike.apache.org) (192.87.106.230) by apache.org (qpsmtpd/0.29) with ESMTP; Thu, 18 Feb 2010 17:00:44 +0000 X-ASF-Spam-Status: No, hits=-2000.0 required=10.0 tests=ALL_TRUSTED X-Spam-Check-By: apache.org Received: from [140.211.11.4] (HELO eris.apache.org) (140.211.11.4) by apache.org (qpsmtpd/0.29) with ESMTP; Thu, 18 Feb 2010 17:00:35 +0000 Received: by eris.apache.org (Postfix, from userid 65534) id E59A123889FF; Thu, 18 Feb 2010 17:00:14 +0000 (UTC) Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Subject: svn commit: r911491 - /httpd/site/trunk/docs/dev/guidelines.html Date: Thu, 18 Feb 2010 17:00:14 -0000 To: cvs@httpd.apache.org From: poirier@apache.org X-Mailer: svnmailer-1.0.8 Message-Id: <20100218170014.E59A123889FF@eris.apache.org> X-Virus-Checked: Checked by ClamAV on 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 @@ + CHANGES file and Subversion logs + + + + +

+
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.
+ + + + + +
+ + Subversion log + +
+
+
The Subversion commit log message contains any information needed by +
+
fellow developers or other people researching source code changes/fixes
+
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)
+
+
+
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.
+
Example log message: + +
+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 <janedoe example.com>
+Reviewed by: susiecommitter
+
+
+
Commit messages can be minimal when making routine updates to STATUS, +for example to propose a backport or vote.
+
+
+ + + + + +
+ + CHANGES + +
+
+
CHANGES is the subset of the information that end users need to see +when they upgrade from one release to the next:
+
what can I now do that I couldn't do before
+
what problems that we anticipate a user could have suffered from are now fixed
+
all security fixes included, with CVE number. (If not available at +the time of the commit, add later.)
+
+
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:
+
Fixes for bugs introduced after the last release don't belong in CHANGES.
+
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.)
+
Documentation fixes, whether for end users or developers, don't +belong in CHANGES.
+
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.
+
The attribution for the change is anyone responsible for the code changes.
+
+
+ + + + + +
+ + Formatting + +
+
+
Identify non-committers by name, and their email in obfuscated +form if available. The obfuscation is done by replacing "@" with a +space and adding "<" and ">" around the address. For example, +change user@example.com to <user example.com>. +
+
Identify committers with their Apache userid, e.g. xyz +(no domain name needed).
+
If the change is related to a bugzilla issue, include the PR number +in the log in the format:
+PR nnnnn
+
+
Security-related changes should start like this:
+  *) SECURITY: CVE-YYYY-NNNN (cve.mitre.org)
+  xxxxxxxxxx
+
+
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.
+
Example CHANGES entries: + +
+  *) SECURITY: CVE-2009-3095 (cve.mitre.org)
+     mod_proxy_ftp: sanity check authn credentials.
+     [Stefan Fritsch <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]
+
+
+
+
+

+ + + + +

+ Patch Format