poi-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ye...@apache.org
Subject svn commit: r1077880 - in /poi/trunk: patch.xml src/documentation/content/xdocs/guidelines.xml
Date Fri, 04 Mar 2011 11:15:44 GMT
Author: yegor
Date: Fri Mar  4 11:15:43 2011
New Revision: 1077880

URL: http://svn.apache.org/viewvc?rev=1077880&view=rev
Log:
ant target to create patches

Added:
    poi/trunk/patch.xml   (with props)
Modified:
    poi/trunk/src/documentation/content/xdocs/guidelines.xml

Added: poi/trunk/patch.xml
URL: http://svn.apache.org/viewvc/poi/trunk/patch.xml?rev=1077880&view=auto
==============================================================================
--- poi/trunk/patch.xml (added)
+++ poi/trunk/patch.xml Fri Mar  4 11:15:43 2011
@@ -0,0 +1,76 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+   Licensed to the Apache Software Foundation (ASF) under one or more
+   contributor license agreements.  See the NOTICE file distributed with
+   this work for additional information regarding copyright ownership.
+   The ASF licenses this file to You under the Apache License, Version 2.0
+   (the "License"); you may not use this file except in compliance with
+   the License.  You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+-->
+<!--
+  =======================================================================
+   Use Apache Ant to generate a patch file.
+  =======================================================================
+-->
+<project name="create-patch" default="patchpackage" basedir=".">
+    <property environment="env"/>
+    <property name="patch.package" value="patch.tar.gz"/>
+    <property name="patch.file" value="patch.txt"/>
+
+    <condition property="svn.found">
+        <or>
+            <available file="svn" filepath="${env.PATH}"/>
+            <available file="svn.exe" filepath="${env.PATH}"/>
+            <available file="svn.exe" filepath="${env.Path}"/>
+        </or>
+    </condition>
+
+    <target name="createpatch">
+        <fail unless="svn.found" message="You need a version of svn to create the patch"/>
+        <exec executable="svn" output="${patch.file}">
+            <arg value="diff"/>
+        </exec>
+    </target>
+
+    <target name="newfiles">
+        <exec executable="svn" output="${patch.file}.tmp">
+            <arg value="status"/>
+        </exec>
+
+       <!-- prepare the list of files to include in patch.tar.gz --> 
+       <loadfile srcfile="${patch.file}.tmp" property="tar.file.list">  
+         <filterchain>  
+            <!-- capture any new files -->
+            <linecontainsregexp>
+                <regexp pattern="(\?|A)......"/>
+            </linecontainsregexp>
+            <!-- filter out the first six characters -->
+            <tokenfilter>
+              <replaceregex pattern="(.......)" replace=""/>
+            </tokenfilter>
+            <!--remove line breaks -->
+            <striplinebreaks/>
+          </filterchain> 
+       </loadfile>  
+    </target>
+
+    <target name="patchpackage" depends="createpatch,newfiles">
+       <delete file="${patch.package}"/> 
+       <tar includes="${tar.file.list}"
+            excludes="${patch.file}"  
+            destfile="${patch.package}"   
+            basedir="." 
+            compression="gzip" >          
+       </tar>  
+       <delete file="${patch.file}.tmp"/>
+    </target>
+
+</project>

Propchange: poi/trunk/patch.xml
------------------------------------------------------------------------------
    svn:executable = *

Modified: poi/trunk/src/documentation/content/xdocs/guidelines.xml
URL: http://svn.apache.org/viewvc/poi/trunk/src/documentation/content/xdocs/guidelines.xml?rev=1077880&r1=1077879&r2=1077880&view=diff
==============================================================================
--- poi/trunk/src/documentation/content/xdocs/guidelines.xml (original)
+++ poi/trunk/src/documentation/content/xdocs/guidelines.xml Fri Mar  4 11:15:43 2011
@@ -138,6 +138,9 @@
      <li>Take a look at all the <link href="https://issues.apache.org/bugzilla/buglist.cgi?product=POI;bug_status=NEW;bug_status=NEEDINFO">unresolved
issues in the bug database</link>, and see if you can help with testing or patches for
them</li>
      <li>Add in new features, see <link href="http://issues.apache.org/bugzilla/buglist.cgi?product=POI">Bug
database</link> for suggestions.</li>
    </ul>
+
+   <p>The Apache <link href="http://www.apache.org/dev/contributors.html">Contributors
Tech Guide</link> gives a good overview how to start contributing patches.</p>

+
    <p>The Nutch project also have a very useful guide on becoming a 
     new developer in their project. While it is written for their project,
     a large part of it will apply to POI too. You can read it at
@@ -146,15 +149,12 @@
     Project</link> also provides guidance and mentoring for new contributors.</p>
   </section>
   <section><title>Submitting Patches</title>
-   <p>
-     Create patches by getting the latest sources from Subversion.
-     Alter or add files as appropriate.  Then, from the poi directiory,
-     type svn diff > mypatch.patch.  This will capture all of your changes
-     in a patch file of the appropriate format. However, svn diff won't
-     capture any new files you may have added. So, if you've added any 
-     files, create an archive (tar.bz2 preferred as its the smallest) in a 
-     path-preserving archive format, relative to your poi directory. 
-     You'll attach both files in the next step.
+   <p> 
+     Patches are submitted via the <link href="http://issues.apache.org/bugzilla/buglist.cgi?product=POI">Bug
Database</link>.  
+     Create a new bug, set the subject to [PATCH] followed by a brief description.  Explain
you patch and any special instructions and submit/save it.  
+     Next, go back to the bug, and create attachements for the patch files you
+     created.  Be sure to describe not only the files purpose, but its format. 
+     (Is that ZIP or a tgz or a bz2 or what?).
    </p>
    <p>
      Ideally, patches should be submitted early and often. This is for
@@ -169,49 +169,70 @@
      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> 
-     Patches are submitted via the <link href="http://issues.apache.org/bugzilla/buglist.cgi?product=POI">Bug
Database</link>.  
-     Create a new bug, set the subject to [PATCH] followed by a brief description.  Explain
you patch and any special instructions and submit/save it.  
-     Next, go back to the bug, and create attachements for the patch files you
-     created.  Be sure to describe not only the files purpose, but its format. 
-     (Is that ZIP or a tgz or a bz2 or what?).
-   </p>
-   <p>
-     Make sure your patches include the @author tag on any files you've altered
-     or created.  Make sure you've documented your changes and altered the 
-     examples/etc to reflect them.  Any new additions should have unit tests.
-     Lastly, ensure that you've provided approriate javadoc.  (see 
-     <link href="http://poi.apache.org/resolutions/res001.html">Coding
-     Standards</link>).  Patches that are of low quality may be rejected or 
-     the contributer may be asked to bring them up to spec.
-   </p>
-   <p>If you use a unix shell, you may find the following following
-    sequence of commands useful for building the files to attach.</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>
    <source>
-# Run this in the root of the checkout, i.e. the directory holding
-#  build.xml and poi.pom
-
-# Build the directory to hold new files
-mkdir /tmp/poi-patch/
-mkdir /tmp/poi-patch/new-files/
-
-# Get changes to existing files
-svn diff > /tmp/poi-patch/diff.txt
-
-# Capture any new files, as svn diff won't include them
-# Preserve the path
-svn status | grep "^\?" | awk '{printf "cp --parents %s /tmp/poi-patch/new-files/\n", $2
}' | sh -s
-
-# tar up the new files
-cd /tmp/poi-patch/new-files/
-tar jcvf ../new-files.tar.bz2
-cd ..
-
-# Upload these to bugzilla
-echo "Please upload to bugzilla:"
-echo "   /tmp/poi-patch/diff.txt"
-echo "   /tmp/poi-patch/new-files.tar.bz2"
+    ant -f patch.xml
    </source>
+  <p>
+    This will create a file named patch.tar.gz that will contain a unified diff of files
that have been modified 
+    and also include files that have been added. Review the file for completeness and correctness.
This approach 
+    is recommended because it standardizes the way in which patch files are constructed.
It also eliminates the 
+    chance of you missing to submit new files that constitute part of the patch. 
+  </p>
+  </section>
+    <section><title>Approach 2 - the manual way</title>
+    <p>
+      Patches to existing files should be generated with svn diff filename and save the output
to a file. 
+      if you want to get the changes made to multiple files in a directory , just use svn
diff. 
+      then, tar and gzip the patch file as well as any new files that you have added. 
+    </p>
+     <p>If you use a unix shell, you may find the following following
+      sequence of commands useful for building the files to attach.</p>
+     <source>
+  # run this in the root of the checkout, i.e. the directory holding
+  #  build.xml and poi.pom
+
+  # build the directory to hold new files
+  mkdir /tmp/poi-patch/
+  mkdir /tmp/poi-patch/new-files/
+
+  # get changes to existing files
+  svn diff > /tmp/poi-patch/diff.txt
+
+  # capture any new files, as svn diff won't include them
+  # preserve the path
+  svn status | grep "^\?" | awk '{printf "cp --parents %s /tmp/poi-patch/new-files/\n", $2
}' | sh -s
+
+  # tar up the new files
+  cd /tmp/poi-patch/new-files/
+  tar jcvf ../new-files.tar.bz2
+  cd ..
+
+  # upload these to bugzilla
+  echo "please upload to bugzilla:"
+  echo "   /tmp/poi-patch/diff.txt"
+  echo "   /tmp/poi-patch/new-files.tar.bz2"
+     </source>
+    </section>
+    <section><title>checklist before submitting a patch</title>
+      <ul>
+        <li>added code complies with <link href="http://poi.apache.org/resolutions/res001.html">coding
standards</link></li>
+        <li>added code compiles and runs on java 1.5</li>
+        <li>new java files begin with the <link href="http://www.apache.org/foundation/licence-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>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>
+      </ul> 
+    </section>
   </section>
 
   <section><title>Mentoring and Committership</title>



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


Mime
View raw message