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