From 4a3e42987ec2d870812b3df7455acca26f5b82ce Mon Sep 17 00:00:00 2001 From: Nick Burch Date: Fri, 2 Jul 2010 15:51:48 +0000 Subject: [PATCH] Update the contributor guidelines (microsoft docs, smaller patches are better etc), and ensure we only have the one copy in /guidelines.html git-svn-id: https://svn.apache.org/repos/asf/poi/trunk@960038 13f79535-47bb-0310-9956-ffa450edef68 --- .../content/xdocs/casestudies.xml | 2 +- .../content/xdocs/getinvolved/book.xml | 38 ---- .../content/xdocs/getinvolved/branching.xml | 115 ---------- .../content/xdocs/getinvolved/index.xml | 197 ------------------ .../content/xdocs/guidelines.xml | 86 ++++++-- .../content/xdocs/hwpf/index.xml | 4 +- .../content/xdocs/plan/index.xml | 2 +- .../xdocs/spreadsheet/hacking-hssf.xml | 2 +- .../content/xdocs/spreadsheet/how-to.xml | 2 +- .../content/xdocs/subversion.xml | 2 +- .../content/xdocs/trans/de/book.xml | 2 +- .../content/xdocs/trans/es/book.xml | 2 +- .../content/xdocs/trans/es/casestudies.xml | 2 +- .../content/xdocs/trans/guidelines.xml | 2 +- src/documentation/skinconf.xml | 2 +- 15 files changed, 81 insertions(+), 379 deletions(-) delete mode 100644 src/documentation/content/xdocs/getinvolved/book.xml delete mode 100644 src/documentation/content/xdocs/getinvolved/branching.xml delete mode 100644 src/documentation/content/xdocs/getinvolved/index.xml diff --git a/src/documentation/content/xdocs/casestudies.xml b/src/documentation/content/xdocs/casestudies.xml index 3646c42b19..044b0e690b 100644 --- a/src/documentation/content/xdocs/casestudies.xml +++ b/src/documentation/content/xdocs/casestudies.xml @@ -46,7 +46,7 @@

We are actively seeking case studies for this page (after all it just started). To submit a case study, either - + submit a patch for this page or email it to the mailing list (with [PATCH] prefixed subject, please). diff --git a/src/documentation/content/xdocs/getinvolved/book.xml b/src/documentation/content/xdocs/getinvolved/book.xml deleted file mode 100644 index d139954975..0000000000 --- a/src/documentation/content/xdocs/getinvolved/book.xml +++ /dev/null @@ -1,38 +0,0 @@ - - - - - - -

- - - - - - - - - - - diff --git a/src/documentation/content/xdocs/getinvolved/branching.xml b/src/documentation/content/xdocs/getinvolved/branching.xml deleted file mode 100644 index 166575be4e..0000000000 --- a/src/documentation/content/xdocs/getinvolved/branching.xml +++ /dev/null @@ -1,115 +0,0 @@ - - - - - - -
- Branching - - - -
- - -
Branching Conventions -

- Branches are tagged in the following way: -

-
    -
  • REL_1_5_BRANCH
    • -
  • REL_2_0_BRANCH
    • -
-

- Merge points should be tagged as follows: -

-
    -
  • REL_1_5_BRANCH_MERGE1
    • -
  • REL_1_5_BRANCH_MERGE2
    • -
  • etc...
    • -
-

- Releases should be tagged as: -

-
    -
  • REL_1_5
    • -
  • REL_1_5_1
    • -
  • REL_1_5_2
    • -
  • etc...
    • -
- -
-
Branching Advise -

- Don't forget which branch you are currently on. This is critically - important. Committing stuff to the wrong branch causes all sorts of - headaches. Best to name your checkout after the branch you are on. -

-
-
Who Manages Branching? -

- All branching is currently managed by Glen Stampoultzis. If you wish - to create your own branch please let him know. Merging is also - handled by Glen. Just pop him a mail if you feel it's necessary to - create a branch or perform a merge. -

-

- The reason to go through a single point for branching is that it can be - an easy thing to get wrong. Having a single person managing branches - means there is less chance of getting getting our wires crossed with this - difficult area of CVS. -

-
-
Currently Active Branches -

- The following branches are currently active: -

- - - - - - - - - - - - - -
- Branch - - Description -
- HEAD - - This is the trunk and is always active. Currently it is being used to continue development - of the 2.0 release. -
- REL_1_5_BRANCH - - All bug fixes not specifically relevant to the 2.0 work should be placed in this branch. - From here they will merged back to the trunk and the merge point marked. -
-
- - - diff --git a/src/documentation/content/xdocs/getinvolved/index.xml b/src/documentation/content/xdocs/getinvolved/index.xml deleted file mode 100644 index 1deb9397bb..0000000000 --- a/src/documentation/content/xdocs/getinvolved/index.xml +++ /dev/null @@ -1,197 +0,0 @@ - - - - - -
- Contribution to POI - - - - - - -
- - - -
Introduction -
Disclaimer -

- Any information in here that might be perceived as legal information is - informational only. We're not lawyers, so consult a legal professional - if needed. -

-
-
The Licensing -

- The POI project is OpenSource - and developed/distributed under the - Apache Software License. Unlike other licenses this license allows - free open source development; however, it does not require you to release - your source or use any particular license for your source. If you wish - to contribute to POI (which you're very welcome and encouraged to do so) - then you must agree to release the rights of your source to us under this - license. -

-
-
Publicly Available Information on the file formats -

- In early 2008, Microsoft made a fairly complete set of documentation - on the binary file formats freely and publicly available. These were - released under the Open - Specification Promise, which does allow us to use them for - building open source software under the - Apache Software License. -

-

- You can download the documentation on Excel, Word, PowerPoint and - Escher (drawing) from - http://www.microsoft.com/interop/docs/OfficeBinaryFormats.mspx. - Documentation on a few of the supporting technologies used in these - file formats can be downloaded from - http://www.microsoft.com/interop/docs/supportingtechnologies.mspx. -

-

- Previously, Microsoft published a book on the Excel 97 file format. - It can still be of plenty of use, and is handy dead tree form. Pick up - a copy of "Excel 97 Developer's Kit" from your favourite second hand - book store. -

-

- The newer Office Open XML (ooxml) file formats are documented as part - of the ECMA / ISO standardisation effort for the formats. This - documentation is quite large, but you can normally find the bit you - need without too much effort! This can be downloaded from - http://www.ecma-international.org/publications/standards/Ecma-376.htm, - and is also under the OSP. -

-

- It is also worth checking the documentation and code of the other - open source implementations of the file formats. -

-
-
I just signed an NDA to get a spec from Microsoft and I'd like to contribute -

- In short, stay away, stay far far away. Implementing these file formats - in POI is done strictly by using public information. Public information - includes sources from other open source projects, books that state the - purpose intended is for allowing implementation of the file format and - do not require any non-disclosure agreement and just hard work. - We are intent on keeping it - legal, by contributing patches you agree to do the same. -

-

- If you've ever received information regarding the OLE 2 Compound Document - Format under any type of exclusionary agreement from Microsoft, or - (possibly illegally) received such information from a person bound by - such an agreement, you cannot participate in this project. (Sorry) -

-

- Those submitting patches that show insight into the file format may be - asked to state explicitly that they have only ever read the publicly - available file format information, and not any received under an NDA - or similar. -

-
-
-
I just want to get involved but don't know where to start -
    -
  • Read the rest of the website, understand what POI is and what it does, - the project vision, etc.
    • -
  • Use POI a bit, look for gaps in the documentation and examples.
    • -
  • Join the mailing lists and share your knowledge with others.
    • -
  • Get Subversion and check out the POI source tree
    • -
  • Documentation is always the best place to start contributing, maybe you found that if the documentation just told you how to do X then it would make more sense, modify the documentation.
    • -
  • Contribute examples - if there's something people are often asking about on the user list which isn't covered in the documentation or current examples, try writing an example of this and uploading it as a patch.
    • -
  • Get used to building POI, you'll be doing it a lot, be one with the build, know its targets, etc.
    • -
  • Write Unit Tests. Great way to understand POI. Look for classes that aren't tested, or aren't tested on a public/protected method level, start there.
    • -
  • Download the file format documentation from Microsoft - - OLE2 Binary File Formats or - OOXML XML File Formats
    • -
  • Submit patches (see below) of your contributions, modifications.
    • -
  • Check the bug database for simple problem reports, and write a patch to fix the problem
    • -
  • Add in new features, see Bug database for suggestions.
    • -
-

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 - http://wiki.apache.org/nutch/Becoming_A_Nutch_Developer

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

-

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

- -# 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" - -
- - - diff --git a/src/documentation/content/xdocs/guidelines.xml b/src/documentation/content/xdocs/guidelines.xml index 4b6e5aff7c..6cefb8526a 100644 --- a/src/documentation/content/xdocs/guidelines.xml +++ b/src/documentation/content/xdocs/guidelines.xml @@ -23,10 +23,8 @@
Apache POI - Contribution Guidelines - - - - + +
@@ -93,24 +91,30 @@
I just signed an NDA to get a spec from Microsoft and I'd like to contribute

In short, stay away, stay far far away. Implementing these file formats - in POI is done strictly by using public information. Public information + in POI is done strictly by using public information. Most of this Public + Information currently comes from the documentation that Microsoft + makes freely available (see above). The rest of the public information includes sources from other open source projects, books that state the purpose intended is for allowing implementation of the file format and do not require any non-disclosure agreement and just hard work. - We are intent on keeping it - legal, by contributing patches you agree to do the same. + We are intent on keeping it legal, by contributing patches you agree to + do the same.

If you've ever received information regarding the OLE 2 Compound Document Format under any type of exclusionary agreement from Microsoft, or - (possibly illegally) received such information from a person bound by - such an agreement, you cannot participate in this project. (Sorry) + received such information from a person bound by such an agreement, you + cannot participate in this project. Sorry. Well, unless you can persuade + Microsoft to release you from the terms of the NDA on the grounds that + most of the information is now publically available. However, if you have + been party to a Microsoft NDA, you will need to get clearance from Microsoft + before contributing.

Those submitting patches that show insight into the file format may be asked to state explicitly that they have only ever read the publicly available file format information, and not any received under an NDA - or similar. + or similar, and have only made us of the public documentation.

@@ -130,12 +134,15 @@ OOXML XML File Formats
  • Submit patches (see below) of your contributions, modifications.
  • Check the bug database for simple problem reports, and write a patch to fix the problem
    • +
  • Review existing patches in the bug database, and report if they still apply, if they need unit tests atc.
  • Add in new features, see Bug database for suggestions.

    • 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 - http://wiki.apache.org/nutch/Becoming_A_Nutch_Developer

    + http://wiki.apache.org/nutch/Becoming_A_Nutch_Developer. The + Apache Community Development + Project also provides guidance and mentoring for new contributors.

    Submitting Patches

    @@ -148,6 +155,19 @@ path-preserving archive format, relative to your poi directory. You'll attach both files in the next step.

    +

    + Ideally, patches should be submitted early and often. This is for + two key reasons. Firstly, it's much easier to review smaller patches + than large ones. This means that smaller patches are much more likely + to be applied to SVN in a timely fashion. Secondly, by sending in your + patches earlier rather than later, it's much easier to get feedback + on your coding and direction. If you've missed an easier way to do something, + or are duplicating some (probably hidden) existing code, or taking things + in an unusual direction, it's best to get the feedback sooner rather than + later! As such, when submitting patches to POI, as with other Apache + 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. @@ -179,8 +199,7 @@ 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 +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/ @@ -194,10 +213,43 @@ echo " /tmp/poi-patch/new-files.tar.bz2"

    +
    Mentoring and Committership +

    The POI project will generally offer committership to contributors who send + in consistently good patches over a period of several months.

    +

    The requirement for "good patches" generally means patches which can be applied + to SVN with little or no changes. These patches should include unit test, and + appropriate documentation. Whilst your first patch to POI may require quite a + bit of work before it can be committed by an existing committer, with any luck + your later patches will be applied with no / minor tweaks. Please do take note + of any changes required by your earlier patches, to learn for later ones! If + in doubt, ask on the dev mailing list.

    +

    The requirement for patches over several months is to ensure that committers + remain with the project. It's very easy for a good developer to fire off half + a dozen good patches in the couple of weeks that they're working on a POI + powered project. However, if that developer then moves away, and stops + contributing to POI after that spurt, then they're not a good candidate for + committership. As such, we generally require people to stay around for a while, + submitting patches and helping on the mailing list before considering them + for committership.

    +

    Where possible, patches should be submitted early and often. For more details + on this, please see the "Submitting Patches" section above.

    + +

    Where possible, the existing developers will try to help and mentor new + contributors. However, everyone involved in POI is a volunteer, and it may + happen that your first few patches come in at a time when all the committers + are very busy. Do please have patience, and remember to use the + dev mailing list so that other + contributors can assist you!

    +

    For more information on getting started at Apache, mentoring, and local + Apache Committers near you who can offer advice, please see the + Apache Community Development + Project website.

    +
    + - diff --git a/src/documentation/content/xdocs/hwpf/index.xml b/src/documentation/content/xdocs/hwpf/index.xml index 1d14be318b..dfae6e27d1 100644 --- a/src/documentation/content/xdocs/hwpf/index.xml +++ b/src/documentation/content/xdocs/hwpf/index.xml @@ -68,7 +68,7 @@

    If you come across a feature in XWPF that you need, and isn't currently there, please do send in a patch to add the extra functionality! More details on contributing patches are available on the "Contribution to POI" page.

    + href="../guidelines.html">"Contribution to POI" page.

    @@ -122,7 +122,7 @@ code easily. If you need any help getting started with JUnit test cases for HWPF, please ask on the developers' mailing list! If you show that you are prepared to stick at it you will most likely be given SVN commit - access. See "Contribution to POI" page + access. See "Contribution to POI" page for more details and help getting started.

    Of course we will help you as best as we can. However, presently there diff --git a/src/documentation/content/xdocs/plan/index.xml b/src/documentation/content/xdocs/plan/index.xml index 04ce89dfe3..5e8aa4e309 100644 --- a/src/documentation/content/xdocs/plan/index.xml +++ b/src/documentation/content/xdocs/plan/index.xml @@ -50,7 +50,7 @@

    Anyone can participate in this process. Please get involved in discussion on dev and contribute patches for these summary planning - documents via the normal contribution + documents via the normal contribution process.

    diff --git a/src/documentation/content/xdocs/spreadsheet/hacking-hssf.xml b/src/documentation/content/xdocs/spreadsheet/hacking-hssf.xml index 7247ad0ee7..eb10f4fc6b 100644 --- a/src/documentation/content/xdocs/spreadsheet/hacking-hssf.xml +++ b/src/documentation/content/xdocs/spreadsheet/hacking-hssf.xml @@ -83,7 +83,7 @@ and work your way up.

    What Else Should I Know? -

    Make sure you read the contributing section +

    Make sure you read the contributing section as it contains more generation information about contributing to POI in general.

    diff --git a/src/documentation/content/xdocs/spreadsheet/how-to.xml b/src/documentation/content/xdocs/spreadsheet/how-to.xml index 9aa863ab54..35e4a00030 100644 --- a/src/documentation/content/xdocs/spreadsheet/how-to.xml +++ b/src/documentation/content/xdocs/spreadsheet/how-to.xml @@ -736,7 +736,7 @@ yet. When it does something, we'll document it.

  • Performance: POI currently uses a lot of memory for large sheets.
  • Charts: This is a hard problem, with very little documentation.
    • -

    So jump in!

    +

    So jump in!

    diff --git a/src/documentation/content/xdocs/subversion.xml b/src/documentation/content/xdocs/subversion.xml index 6e5d342eb6..4b8d298899 100644 --- a/src/documentation/content/xdocs/subversion.xml +++ b/src/documentation/content/xdocs/subversion.xml @@ -70,7 +70,7 @@

    If you are not a Committer, but you want to submit patches or even request commit privileges, please see our - Guidelines for more + Guidelines for more information.

    Git access to POI sources diff --git a/src/documentation/content/xdocs/trans/de/book.xml b/src/documentation/content/xdocs/trans/de/book.xml index 641170ebab..0356d949d6 100644 --- a/src/documentation/content/xdocs/trans/de/book.xml +++ b/src/documentation/content/xdocs/trans/de/book.xml @@ -42,7 +42,7 @@ - + diff --git a/src/documentation/content/xdocs/trans/es/book.xml b/src/documentation/content/xdocs/trans/es/book.xml index 3defdaf7eb..0e9bedd9d1 100644 --- a/src/documentation/content/xdocs/trans/es/book.xml +++ b/src/documentation/content/xdocs/trans/es/book.xml @@ -47,7 +47,7 @@ - + diff --git a/src/documentation/content/xdocs/trans/es/casestudies.xml b/src/documentation/content/xdocs/trans/es/casestudies.xml index 7aa558bd6b..58a22f38dd 100644 --- a/src/documentation/content/xdocs/trans/es/casestudies.xml +++ b/src/documentation/content/xdocs/trans/es/casestudies.xml @@ -48,7 +48,7 @@ acaba de comenzarse). Andrew C. Oliver (acoliver at apache dot org) ha accedido a entregar unas cuantas Camisetas con el logotipo de POI para los primeros y mejores envíos. Para enviar un estudio de un caso, puedes - + enviar un parche para esta página o enviarlo por correo electrónico a la lista de correo (con [PATCH] como prefijo en el asunto, por favor). diff --git a/src/documentation/content/xdocs/trans/guidelines.xml b/src/documentation/content/xdocs/trans/guidelines.xml index 7564ab743e..9a90ff377e 100644 --- a/src/documentation/content/xdocs/trans/guidelines.xml +++ b/src/documentation/content/xdocs/trans/guidelines.xml @@ -80,7 +80,7 @@

    Submitting translations is simple, you follow the same - instructions as you would for submitting a code patch. + instructions as you would for submitting a code patch. Remeber to always generate patchs in diff -u format preserving the context relative to the jakarta-poi directory. Also remember to submit any new files in a directory preserving archive format. Never post these to the list, always use Bugzilla diff --git a/src/documentation/skinconf.xml b/src/documentation/skinconf.xml index 5c972d1b95..ad5b921bed 100644 --- a/src/documentation/skinconf.xml +++ b/src/documentation/skinconf.xml @@ -114,7 +114,7 @@ be used to configure the chosen Forrest skin. - 2002-2009 + 2002-2010 The Apache Software Foundation