diff --git a/patch.xml b/patch.xml new file mode 100755 index 000000000..56852f4b5 --- /dev/null +++ b/patch.xml @@ -0,0 +1,76 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/src/documentation/content/xdocs/guidelines.xml b/src/documentation/content/xdocs/guidelines.xml index ecb51c84d..eb0fe14d5 100644 --- a/src/documentation/content/xdocs/guidelines.xml +++ b/src/documentation/content/xdocs/guidelines.xml @@ -138,6 +138,9 @@
  • Take a look at all the unresolved issues in the bug database, and see if you can help with testing or patches for them
  • Add in new features, see Bug database for suggestions.
    • + +

    The Apache Contributors Tech Guide gives a good overview how to start contributing patches.

    +

    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 also provides guidance and mentoring for new contributors.

    Submitting Patches -

    - 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 Bug Database. + 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?).

    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.

    -

    - Patches are submitted via the Bug Database. - 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?). -

    -

    - 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 - Coding - Standards). Patches that are of low quality may be rejected or - the contributer may be asked to bring them up to spec. -

    -

    If you use a unix shell, you may find the following following - sequence of commands useful for building the files to attach.

    +

    You may create your patch file using either of the following approaches (the committers recommend the first):

    +
    Approach 1 - use Ant +

    Use Ant to generate a patch file to POI:

    -# 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 +

    + 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. +

    +
    +
    Approach 2 - the manual way +

    + 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. +

    +

    If you use a unix shell, you may find the following following + sequence of commands useful for building the files to attach.

    + + # 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" + +
    +
    checklist before submitting a patch + +
    Mentoring and Committership