httpd-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From traw...@apache.org
Subject cvs commit: httpd-site/xdocs/dev patches.xml
Date Thu, 20 Nov 2003 13:12:13 GMT
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 &gt;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 &lt;PR-number&gt;]" 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 &gt;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 &lt;PR-number&gt;]" 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>
   
  
  
  

Mime
View raw message