diff options
| -rwxr-xr-x | patch.xml | 76 | ||||
| -rw-r--r-- | src/documentation/content/xdocs/guidelines.xml | 113 |
2 files changed, 143 insertions, 46 deletions
diff --git a/patch.xml b/patch.xml new file mode 100755 index 0000000000..56852f4b5f --- /dev/null +++ b/patch.xml @@ -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>
diff --git a/src/documentation/content/xdocs/guidelines.xml b/src/documentation/content/xdocs/guidelines.xml index ecb51c84d5..eb0fe14d5c 100644 --- a/src/documentation/content/xdocs/guidelines.xml +++ b/src/documentation/content/xdocs/guidelines.xml @@ -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 + 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/ + # 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 + # 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 + # 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 .. + # 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> + # 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> |