From 024f1d334878c16a950f7e92812ca8096cdbf090 Mon Sep 17 00:00:00 2001 From: PJ Fanning Date: Tue, 8 Jul 2025 12:05:16 +0100 Subject: [PATCH] Update guidelines.xml --- .../content/xdocs/devel/guidelines.xml | 65 +------------------ 1 file changed, 3 insertions(+), 62 deletions(-) diff --git a/src/documentation/content/xdocs/devel/guidelines.xml b/src/documentation/content/xdocs/devel/guidelines.xml index 6f6007227e..8e379befff 100644 --- a/src/documentation/content/xdocs/devel/guidelines.xml +++ b/src/documentation/content/xdocs/devel/guidelines.xml @@ -118,7 +118,7 @@ first and reference it in the PR.

- For Subversion fans, you can add patch files to the Bugzilla issues at + You can add patch files to the Bugzilla issues at Bug Database. If there is already a bug-report, attach it there, otherwise create a new bug, set the subject to [PATCH] followed by a brief description. @@ -148,72 +148,13 @@ is fairly similar as a starting point.

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:

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

-

- To apply a previously generated patch.tar.gz file to a clean subversion checkout, use the following command. - It will unpack the tarball and add new files to the subversion working copy. -

- - ant -f patch.xml apply - -
-
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" - -
-
Approach 3 - the git way +
Using Git

If you are working on a Git clone of Apache POI (see the Version Control page for - more on the read-only Git mirrors), it is possible to generate + more info), it is possible to generate a patch of your changes (including new binary files) using Git.

-

- For new developers, we'd normally suggest using Subversion and - one of the methods above, as they tend to be simpler. For people - who are already proficient with Git, then generating a patch - from Git can be an easy way to contribute! -

When generating a patch / patch set from Git, for many related and small changes a squashed patch is probably best, as it makes the