moparisthebest/poi
1
0
Fork 0
Code Issues Pull Requests Releases 1 Wiki Activity

ant target to create patches

Browse Source 
git-svn-id: https://svn.apache.org/repos/asf/poi/trunk@1077880 13f79535-47bb-0310-9956-ffa450edef68
This commit is contained in:
Yegor Kozlov 2011-03-04 11:15:43 +00:00
parent 817a44dcd4
commit 079fc19d61
2 changed files with 147 additions and 50 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

76
patch.xml Executable file
View File

@ -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>

119
src/documentation/content/xdocs/guidelines.xml
View File

@ -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
@ -147,14 +150,11 @@
</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.
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>