svn commit: r1492795 - /poi/site/src/documentation/content/xdocs/guidelines.xml

[ni...@apache.org]

Author: nick
Date: Thu Jun 13 18:17:16 2013
New Revision: 1492795

URL: http://svn.apache.org/r1492795
Log:
Update the @author part, update how patches are submitted, and add a pragmatic code style section based on what we have tended to follow of late

Modified:
    poi/site/src/documentation/content/xdocs/guidelines.xml

Modified: poi/site/src/documentation/content/xdocs/guidelines.xml
URL: http://svn.apache.org/viewvc/poi/site/src/documentation/content/xdocs/guidelines.xml?rev=1492795&r1=1492794&r2=1492795&view=diff
==============================================================================
--- poi/site/src/documentation/content/xdocs/guidelines.xml (original)
+++ poi/site/src/documentation/content/xdocs/guidelines.xml Thu Jun 13 18:17:16 2013
@@ -35,6 +35,7 @@
      <li><link href="#Introduction">Introduction</link></li>
      <li><link href="#GetInvolved">I just want to get involved, but don't know where to start?</link></li>
      <li><link href="#SubmittingPatches">Submitting Patches</link></li>
+     <li><link href="#CodeStyle">Code Style</link></li>
      <li><link href="#Mentoring">Mentoring and Committership</link></li>
    </ul>
  </section>
@@ -185,6 +186,13 @@
      Software Foundation projects, do please try to submit early and often, rather
      than "throwing a large patch over the wall" at the end.
    </p>
+   <p>
+     A number of Apache projects provide far more comprehensive guides to producing
+     and submitting patches than we do, you may wish to review some of their
+     information if you're unsure. The 
+     <link href="http://commons.apache.org/patches.html">Apache Commons</link> one
+     is fairly similar as a starting point.
+   </p>
   <p>You may create your patch file using either of the following approaches (the committers recommend the first):</p>
   <section><title>Approach 1 - use Ant</title>
   <p>Use Ant to generate a patch file to POI: </p>
@@ -239,18 +247,42 @@
         <li>new java files begin with the <link href="http://www.apache.org/foundation/license-faq.html">
              apache software license</link> statement.</li> 
         <li>the code does not depend on gpl or lgpl code.</li> 
-        <li>the code includes the @author tag on any files you've altered or created.</li>
+        <li>the code doesn't include @author tags</li>
         <li>existing test cases succeed.</li>
         <li>new test cases written and succeed.</li>
         <li>documentation page extended as appropriate.</li>
         <li>diff files generated using svn diff</li>
-        <li>message to dev contains [patch], task name and patch reason in subject.</li>
-        <li>message body contains a rationale for the patch.</li>
-        <li>message attachment contains the patch file(s).</li>
+        <li>the bugzilla subject dev contains [patch], task name and patch reason in subject.</li>
+        <li>the bugzilla description contains a rationale for the patch.</li>
+        <li>attachment to the bugzilla entry contains the patch file(s).</li>
       </ul> 
     </section>
   </section>
 
+  <anchor id="CodeStyle"/>
+  <section><title>Code Style</title>
+    <p>The long standing 
+      <link href="http://poi.apache.org/resolutions/res001.html">Minimal 
+      Coding Standards</link> from 2002 still largely apply to the project.</p>
+    <p>When making changes to an existing file, please try to follow the
+      same style that that file already uses. This will keep things
+      looking similar, and will prevent patches becoming largely about
+      whitespace. Whitespace fixing changes, if needed, should normally be 
+      in their own commit, so that they don't crowd out coding changes 
+      in review.</p>
+    <p>Normally, tabs should not be used to indent code. Instead, spaces
+      should be used. If starting on a fresh file, please use 4 spaces to
+      indent your code. If working on an existing file, please use 
+      whichever of 3 or 4 spaces that file already follows.</p>
+    <p>Normally, braces should open on the same line as the decision
+      statement. Braces should normally close on their own line. Brackets
+      should normally have a space before them when they are the first.</p>
+    <p>Lines normally shouldn't be too long. There's no hard and fast rule,
+      but if you line is getting above about 90 characters think about
+      splitting it, and you should rarely create something over about 100
+      characters without a very good reason!</p>
+  </section>
+
   <anchor id="Mentoring"/>
   <section><title>Mentoring and Committership</title>
    <p>The POI project will generally offer committership to contributors who send



---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@poi.apache.org
For additional commands, e-mail: commits-help@poi.apache.org