From 65989672af13566f02d4abb43d01243dc7412312 Mon Sep 17 00:00:00 2001 From: Yegor Kozlov Date: Fri, 4 Mar 2011 11:15:43 +0000 Subject: [PATCH] ant target to create patches git-svn-id: https://svn.apache.org/repos/asf/poi/trunk@1077880 13f79535-47bb-0310-9956-ffa450edef68 --- patch.xml | 76 ++++++++++++ .../content/xdocs/guidelines.xml | 113 +++++++++++------- 2 files changed, 143 insertions(+), 46 deletions(-) create mode 100755 patch.xml diff --git a/patch.xml b/patch.xml new file mode 100755 index 0000000000..56852f4b5f --- /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 ecb51c84d5..eb0fe14d5c 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 + 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/ + # 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" - + # 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 +
      +
    • added code complies with coding standards
      • +
    • added code compiles and runs on java 1.5
      • +
    • new java files begin with the + apache software license statement.
      • +
    • the code does not depend on gpl or lgpl code.
      • +
    • the code includes the @author tag on any files you've altered or created.
      • +
    • existing test cases succeed.
      • +
    • new test cases written and succeed.
      • +
    • documentation page extended as appropriate.
      • +
    • diff files generated using svn diff
      • +
    • message to dev contains [patch], task name and patch reason in subject.
      • +
    • message body contains a rationale for the patch.
      • +
    • message attachment contains the patch file(s).
      • +
    +
    Mentoring and Committership -- 2.39.5