apr-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From wr...@apache.org
Subject svn commit: r377079 - /apr/site/trunk/xdocs/patches.xml
Date Sat, 11 Feb 2006 23:08:33 GMT
Author: wrowe
Date: Sat Feb 11 15:08:31 2006
New Revision: 377079

URL: http://svn.apache.org/viewcvs?rev=377079&view=rev
Log:

  Let's state some things more plainly, and provide some resources for users
  to provide us unidiffs.  Failing that, make it clear that garbage just
  isn't likely to be considered.


Modified:
    apr/site/trunk/xdocs/patches.xml

Modified: apr/site/trunk/xdocs/patches.xml
URL: http://svn.apache.org/viewcvs/apr/site/trunk/xdocs/patches.xml?rev=377079&r1=377078&r2=377079&view=diff
==============================================================================
--- apr/site/trunk/xdocs/patches.xml (original)
+++ apr/site/trunk/xdocs/patches.xml Sat Feb 11 15:08:31 2006
@@ -13,8 +13,10 @@
 who use it in their own projects.  We want to make it as easy as possible for
 people to contribute code.  However, we do have some expectations of code that
 is contributed.  This is to help us review code as quickly as possible.  If
-code is contributed that doesn't follow these guidelines, it will still be
-reviewed, but it will most likely take longer.</p>
+code is contributed that doesn't follow these guidelines, it might still be
+reviewed, but it will take longer and attract the attention of fewer 
+developers.  When you contribute, please remember that anyone evaluating your 
+suggestion is a voulenteer contributor, just like yourself.</p>
 
 </section>
 
@@ -40,35 +42,80 @@
 partly due to APR's httpd lineage) is that the input values do not need to be
 checked for correctness.  It is the responsibility of the calling program that
 uses APR to ensure that the input parameters are what APR expects.  If the
-input parameters are invalid (NULL, for example), APR functions will likely
-produce a segfault when it attempts to reference these variables.</p>
+input parameters are invalid (NULL, for example), APR functions are expected
+to produce a segfault when it attempts to reference these variables.  This
+increases the stability of consumer code, by forcing developers to fix code
+which might otherwise silently ignores fatal error conditions.</p>
 
 </section>
 
 <section>
 <title>Patch Format</title>
 
-<p>We prefer that patches be submitted in unified diff format:</p>
+<p>We request that patches be submitted in unified diff format:</p>
 
 <blockquote><code>diff -u file-old.c file.c</code></blockquote>
 
-<p>but that isn't available on all platforms. If your platform doesn't
-support unified diffs, please use a context diff instead:</p>
+<p>or if working with an svn checkout:</p>
+
+<blockquote><code>svn diff file.c</code></blockquote>
+
+<p>where <code>file.c</code> is the file affected.  (Older versions of
diff
+may require -u3 to display lines of context, but the current version of GNU
+diff has deprecated the trailing number for -u and presumes three lines,
+use -U# syntax if you wish to provide more lines of context.)</p>
+
+<p>You can obtain the most sophisticated diff utility from the GNU diffutils
+project:</p>
+
+<blockquote><code><a href="http://www.gnu.org/software/diffutils/diffutils.html"
+>http://www.gnu.org/software/diffutils/diffutils.html</a></code></blockquote>
+
+<p>and Windows users can obtain a native port of diff and other useful utilites
+from:</p>
+
+<blockquote><code><a href="http://unxutils.sourceforge.net/"
+>http://unxutils.sourceforge.net/</a></code></blockquote>
+
+<p>If you <b>cannot</b> produce a unified diff, then at least please submit
+a context diff:</p>
 
 <blockquote><code>diff -C3 file-old.c file.c</code></blockquote>
 
-<p>where <code>file.c</code> is the file affected.  We should be able to
feed
-the patch directly into the "patch" program and have it update the file or set
-of files.  The <code>-C3</code> is very 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>We should be able to feed the patch directly into the "patch" program and 
+have it update the file or set of files.  The <code>-u</code> or 
+<code>-C3</code> is critical; the existing code changes regularly, so having

+context is crucial to understanding your patch and knowing where it all really 
+goes.  Patches without filenames, line numbers and surrounding context become 
+impossible to consider as time goes on.</p>
 
 </section>
 
 <section>
 <title>Submitting Your Patch</title>
 
-<p><b>If</b> you are a subscriber to dev@apr.apache.org, you can simply
post
+<p>The best place to submit your patch is an attachment to a bug report:</p>
+
+<blockquote><code><a href="http://issues.apache.org/bugzilla/"
+>http://issues.apache.org/bugzilla/</a></code></blockquote>
+
+<p>Be certain to 1) research your patch, ensure that it isn't already in an
+existing bug report, and that similiar code hasn't already been committed to
+the working development trunk:</p>
+
+<blockquote><code><a href="http://svn.apache.org/repos/asf/apr/apr/trunk/"
+>http://svn.apache.org/repos/asf/apr/apr/trunk</a></code></blockquote>
+<blockquote><code><a href="http://svn.apache.org/repos/asf/apr/apr-util/trunk/"
+>http://svn.apache.org/repos/asf/apr/apr-util/trunk</a></code></blockquote>
+<blockquote><code><a href="http://svn.apache.org/repos/asf/apr/apr-iconv/trunk/"
+>http://svn.apache.org/repos/asf/apr/apr-iconv/trunk</a></code></blockquote>
+
+<p>Ensure your patch is attached as a text/ type file, and try retrieving it
+yourself after you add it, to ensure that others can, too.  Do not submit links
+to other locations for your patch (or anyone else's patch!), as they will only 
+be considered when submitted directly to the ASF by the original author.</p>
+
+<p><b>If</b> you are a subscriber to dev@apr.apache.org, you can also 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



Mime
View raw message