You are viewing a plain text version of this content. The canonical link for it is here.
Posted to cvs@httpd.apache.org by tr...@apache.org on 2003/11/20 14:12:13 UTC
cvs commit: httpd-site/xdocs/dev patches.xml
trawick 2003/11/20 05:12:13
Modified: docs/dev patches.html
xdocs/dev patches.xml
Log:
Document the new patch submission requirements.
These changes include some hints for tree management from
Glenn <gs-apache-dev at gluelogic.com>. Thanks also to Paul
Reder for reviewing, though I removed the statement that he
had tried to rescue.
Revision Changes Path
1.25 +92 -20 httpd-site/docs/dev/patches.html
Index: patches.html
===================================================================
RCS file: /home/cvs/httpd-site/docs/dev/patches.html,v
retrieving revision 1.24
retrieving revision 1.25
diff -u -r1.24 -r1.25
--- patches.html 9 Nov 2003 23:51:13 -0000 1.24
+++ patches.html 20 Nov 2003 13:12:13 -0000 1.25
@@ -85,7 +85,10 @@
<blockquote>
<p>We have a fairly firmly-set code format we use in our code; it was
one we arrived at through no small amount of debate. The format is
-described in our official <a href="styleguide.html">style guide</a>.</p>
+described in our official <a href="styleguide.html">style guide</a>.
+While there is some code in the project that does not follow the style
+guide, it is generally safe to assume that your code is wrong if it
+is not formatted like the other code in the file.</p>
<p>We also have very high expectations for code quality; and to us this
means the avoidance of excessive static buffers, using the
memory pool mechanism (which ensures proper cleanup), and otherwise
@@ -99,6 +102,52 @@
<table border="0" cellspacing="0" cellpadding="2" width="100%">
<tr><td bgcolor="#525D76">
<font color="#ffffff" face="arial,helvetica,sanserif">
+ <strong>Documentation</strong>
+ </font>
+ </td></tr>
+ <tr><td>
+ <blockquote>
+<p>The Apache documentation needs to be updated for some patches,
+most often for enhancements. You may wish to see if your patch
+is considered generally acceptable before updating the documentation.
+Patches for the documentation are submitted with any code changes in
+the same patch format.</p>
+<p>Please note that for Apache 2.0 and above, most of the
+documentation is generated from XML. Your changes need to be made to
+the XML version. See
+<a href="http://httpd.apache.org/docs-project/docsformat.html">
+http://httpd.apache.org/docs-project/docsformat.html</a> for more
+information.</p>
+ </blockquote>
+ </td></tr>
+</table>
+ <table border="0" cellspacing="0" cellpadding="2" width="100%">
+ <tr><td bgcolor="#525D76">
+ <font color="#ffffff" face="arial,helvetica,sanserif">
+ <strong>Choosing a level of Apache code for comparison</strong>
+ </font>
+ </td></tr>
+ <tr><td>
+ <blockquote>
+<p>Currently, there are three active Apache httpd source trees:</p>
+<ol>
+ <li>Apache httpd 1.3 (apache-1.3 main branch in cvs)</li>
+ <li>Apache httpd 2.0.x (httpd-2.0, APACHE_2_0_BRANCH branch in cvs)</li>
+ <li>Apache httpd 2.1.x (httpd-2.0 main branch in cvs)</li>
+</ol>
+<p>A patch should be created against the last public release or, if
+practical, the latest code in CVS for the relevant source tree.
+Patches created against older releases may not apply to current
+sources.</p>
+<p>Instructions for obtaining a source tree from CVS are at
+<a href="http://httpd.apache.org/dev/anoncvs.txt">
+http://httpd.apache.org/dev/anoncvs.txt</a></p>
+ </blockquote>
+ </td></tr>
+</table>
+ <table border="0" cellspacing="0" cellpadding="2" width="100%">
+ <tr><td bgcolor="#525D76">
+ <font color="#ffffff" face="arial,helvetica,sanserif">
<strong>Patch Format</strong>
</font>
</td></tr>
@@ -115,6 +164,19 @@
important - line numbers can change on a daily basis in some code
files, so having context is crucial to knowing where it all really
goes.</p>
+<p>If multiple files are modified, the following setup can simplify
+the management of original and modified files:</p>
+<ol>
+ <li><BLOCKQUOTE><CODE>cd /sources</CODE></BLOCKQUOTE></li>
+ <li><BLOCKQUOTE><CODE>tar xvzf httpd-2.0.x.tar.gz</CODE></BLOCKQUOTE></li>
+ <li><BLOCKQUOTE><CODE>cp -ax httpd-2.0.x httpd-2.0.x.new</CODE></BLOCKQUOTE></li>
+ <li>edit files in httpd-2.0.x.new and build/test</li>
+ <li><BLOCKQUOTE><CODE>cd /sources</CODE></BLOCKQUOTE></li>
+ <li><BLOCKQUOTE><CODE>diff -ru httpd-2.0.x httpd-2.0.x.new >my.unified.diff.patch</CODE></BLOCKQUOTE></li>
+</ol>
+<p>If your source tree was checked out of CVS,
+<BLOCKQUOTE><CODE>cvs diff -u</CODE></BLOCKQUOTE> will create the
+patch in the correct format.</p>
</blockquote>
</td></tr>
</table>
@@ -126,26 +188,36 @@
</td></tr>
<tr><td>
<blockquote>
-<p><B>If</B> you are a subscriber to dev@httpd.apache.org, you can simply post
-your patch there, with the string "[PATCH]" prefixing your subject
-line, so everyone knows it's a patch. However, it's not guaranteed
-that your Patch will find an advocate within the developers' group;
-if we're too busy working on something else or everyone's on
-vacation, it could get lost in the noise. Feel free to resubmit
-your patch in a week or so if you have not yet received any feedback
-from the developers' group. Another good way to make sure it gets
-on our plate is to submit it through the bug database, at <a href="http://nagoya.apache.org/bugzilla/">
-http://nagoya.apache.org/bugzilla/</a>.</p>
+<p>Traditionally, patches have been submitted on the developer's
+mailing list as well as through the bug database. Unfortunately, this
+has made it hard to easily track the patches. And without being able
+to easily track them, too many of them have been ignored.</p>
+<p>Patches must now be submitted through the bug database, at
+<a href="http://nagoya.apache.org/bugzilla/">http://nagoya.apache.org/bugzilla/</a>
+. You'll need to create a Bugzilla
+account there if you don't already have one. Submit the patch by
+first entering a new bug report. Be sure to specify APR for the
+product if the patch is for a file in srclib/apr or srclib/apr-util.
+The following information is very helpful, when it is available:</p>
+<ol>
+ <li>for Apache httpd 2.0.x bugs, mention whether or not it occurred
+ with Apache httpd 1.3</li>
+ <li>explain how to reproduce the problem and how the patch has been
+ tested</li>
+</ol>
+<p>After the bug report has been created, edit it again and specify
+<b>PatchAvailable</b> as a keyword and then add your patch as a new
+attachment.</p>
+<p>If you wish to discuss the patch on the developer's mailing list,
+prefix your subject line with "[PATCH <PR-number>]" to reference
+your patch submission.</p>
<p>Be aware that the core developers tend to be very conservative
-about what makes it into the core of Apache. Apache has a very
-flexible API, and any advanced functionality is likely to be pushed
-to be a third-party module. Portability fixes are the most
-important; protocol correctness is also critical for us; and we're
-sure there's more dumb mistakes in the code than we could shake a
-stick at. Those will get priority; new functionality may not.</p>
-<p>Also, there are often times when the core developers are in
-"feature freeze", when they are trying to iron out the remaining
-bugs in the code in preparation for a release.</p>
+about what makes it into the core of Apache. Apache has a very
+flexible API, and any advanced functionality is likely to be pushed to
+be a third-party module. Portability fixes are the most important;
+protocol correctness is also critical for us; and we're sure there's
+more dumb mistakes in the code than we could shake a stick at. Those
+will get priority; new functionality may not.</p>
</blockquote>
</td></tr>
</table>
1.7 +94 -22 httpd-site/xdocs/dev/patches.xml
Index: patches.xml
===================================================================
RCS file: /home/cvs/httpd-site/xdocs/dev/patches.xml,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -r1.6 -r1.7
--- patches.xml 9 Nov 2003 23:51:13 -0000 1.6
+++ patches.xml 20 Nov 2003 13:12:13 -0000 1.7
@@ -25,7 +25,10 @@
<p>We have a fairly firmly-set code format we use in our code; it was
one we arrived at through no small amount of debate. The format is
-described in our official <a href="styleguide.html">style guide</a>.</p>
+described in our official <a href="styleguide.html">style guide</a>.
+While there is some code in the project that does not follow the style
+guide, it is generally safe to assume that your code is wrong if it
+is not formatted like the other code in the file.</p>
<p>We also have very high expectations for code quality; and to us this
means the avoidance of excessive static buffers, using the
@@ -37,6 +40,45 @@
</section>
<section>
+<title>Documentation</title>
+
+<p>The Apache documentation needs to be updated for some patches,
+most often for enhancements. You may wish to see if your patch
+is considered generally acceptable before updating the documentation.
+Patches for the documentation are submitted with any code changes in
+the same patch format.</p>
+
+<p>Please note that for Apache 2.0 and above, most of the
+documentation is generated from XML. Your changes need to be made to
+the XML version. See
+<a href="http://httpd.apache.org/docs-project/docsformat.html">
+http://httpd.apache.org/docs-project/docsformat.html</a> for more
+information.</p>
+
+</section>
+
+<section>
+<title>Choosing a level of Apache code for comparison</title>
+
+<p>Currently, there are three active Apache httpd source trees:</p>
+<ol>
+ <li>Apache httpd 1.3 (apache-1.3 main branch in cvs)</li>
+ <li>Apache httpd 2.0.x (httpd-2.0, APACHE_2_0_BRANCH branch in cvs)</li>
+ <li>Apache httpd 2.1.x (httpd-2.0 main branch in cvs)</li>
+</ol>
+
+<p>A patch should be created against the last public release or, if
+practical, the latest code in CVS for the relevant source tree.
+Patches created against older releases may not apply to current
+sources.</p>
+
+<p>Instructions for obtaining a source tree from CVS are at
+<a href="http://httpd.apache.org/dev/anoncvs.txt">
+http://httpd.apache.org/dev/anoncvs.txt</a></p>.
+
+</section>
+
+<section>
<title>Patch Format</title>
<p>We prefer that patches be submitted in unified diff format:</p>
@@ -54,34 +96,64 @@
important - line numbers can change on a daily basis in some code
files, so having context is crucial to knowing where it all really
goes.</p>
+
+<p>If multiple files are modified, the following setup can simplify
+the management of original and modified files:</p>
+
+<ol>
+ <li><BLOCKQUOTE><CODE>cd /sources</CODE></BLOCKQUOTE></li>
+ <li><BLOCKQUOTE><CODE>tar xvzf httpd-2.0.x.tar.gz</CODE></BLOCKQUOTE></li>
+ <li><BLOCKQUOTE><CODE>cp -ax httpd-2.0.x httpd-2.0.x.new</CODE></BLOCKQUOTE></li>
+ <li>edit files in httpd-2.0.x.new and build/test</li>
+ <li><BLOCKQUOTE><CODE>cd /sources</CODE></BLOCKQUOTE></li>
+ <li><BLOCKQUOTE><CODE>diff -ru httpd-2.0.x httpd-2.0.x.new >my.unified.diff.patch</CODE></BLOCKQUOTE></li>
+</ol>
+
+<p>If your source tree was checked out of CVS,
+<BLOCKQUOTE><CODE>cvs diff -u</CODE></BLOCKQUOTE> will create the
+patch in the correct format.</p>
+
</section>
<section>
<title>Submitting your Patch</title>
-<p><B>If</B> you are a subscriber to dev@httpd.apache.org, you can simply post
-your patch there, with the string "[PATCH]" prefixing your subject
-line, so everyone knows it's a patch. However, it's not guaranteed
-that your Patch will find an advocate within the developers' group;
-if we're too busy working on something else or everyone's on
-vacation, it could get lost in the noise. Feel free to resubmit
-your patch in a week or so if you have not yet received any feedback
-from the developers' group. Another good way to make sure it gets
-on our plate is to submit it through the bug database, at <a
-href="http://nagoya.apache.org/bugzilla/">
-http://nagoya.apache.org/bugzilla/</a>.</p>
+<p>Traditionally, patches have been submitted on the developer's
+mailing list as well as through the bug database. Unfortunately, this
+has made it hard to easily track the patches. And without being able
+to easily track them, too many of them have been ignored.</p>
+
+<p>Patches must now be submitted through the bug database, at
+<a
+href="http://nagoya.apache.org/bugzilla/">http://nagoya.apache.org/bugzilla/</a>
+. You'll need to create a Bugzilla
+account there if you don't already have one. Submit the patch by
+first entering a new bug report. Be sure to specify APR for the
+product if the patch is for a file in srclib/apr or srclib/apr-util.
+The following information is very helpful, when it is available:</p>
+
+<ol>
+ <li>for Apache httpd 2.0.x bugs, mention whether or not it occurred
+ with Apache httpd 1.3</li>
+ <li>explain how to reproduce the problem and how the patch has been
+ tested</li>
+</ol>
+
+<p>After the bug report has been created, edit it again and specify
+<b>PatchAvailable</b> as a keyword and then add your patch as a new
+attachment.</p>
+
+<p>If you wish to discuss the patch on the developer's mailing list,
+prefix your subject line with "[PATCH <PR-number>]" to reference
+your patch submission.</p>
<p>Be aware that the core developers tend to be very conservative
-about what makes it into the core of Apache. Apache has a very
-flexible API, and any advanced functionality is likely to be pushed
-to be a third-party module. Portability fixes are the most
-important; protocol correctness is also critical for us; and we're
-sure there's more dumb mistakes in the code than we could shake a
-stick at. Those will get priority; new functionality may not.</p>
-
-<p>Also, there are often times when the core developers are in
-"feature freeze", when they are trying to iron out the remaining
-bugs in the code in preparation for a release.</p>
+about what makes it into the core of Apache. Apache has a very
+flexible API, and any advanced functionality is likely to be pushed to
+be a third-party module. Portability fixes are the most important;
+protocol correctness is also critical for us; and we're sure there's
+more dumb mistakes in the code than we could shake a stick at. Those
+will get priority; new functionality may not.</p>
</section>