src/documentation/content/xdocs/devel/guidelines.xml - poi - Git at Google

 <?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.
    ====================================================================
 -->
 <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "document-v20.dtd">

 <document>
  <header>
   <title>Apache POI™ - Contribution Guidelines</title>
   <authors>
    <person name="Nick Burch" email="dev@poi.apache.org"/>
    <person name="David Fisher" email="dev@poi.apache.org"/>
    </authors>
  </header>

  <body>

  <section><title>Index of Contribution Guidelines</title>
    <ul>
      <li><a href="#Introduction">Introduction</a></li>
      <li><a href="#WhereHelpNeeded">Where is help needed on the project?</a></li>
      <li><a href="#GetInvolved">I just want to get involved, but don't know where to start?</a></li>
      <li><a href="#SubmittingPatches">Submitting Patches</a></li>
      <li><a href="#CodeStyle">Code Style</a></li>
      <li><a href="#Mentoring">Mentoring and Committership</a></li>
      <li><a href="#FileFormatInformation">File Format Information</a></li>
    </ul>
  </section>

  <anchor id="Introduction"/>
  <section><title>Introduction</title>

   <section><title>Disclaimer</title>
    <p>
      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.
    </p>
   </section>

   <section><title>The Licensing</title>
    <p>
      The POI project is <a href="http://www.opensource.org">OpenSource</a>
      and developed/distributed under the <a
      href="https://www.apache.org/foundation/license-faq.html">
      Apache Software License v2</a>.  Unlike some other licenses, the Apache
      license allows free open source development. Unlike some other Open Source
      licenses, it does not require you to release your source or use any
      particular license for your code which builds on top of it. (There are a
      handful of restrictions, especially around attribution, notices and trademarks,
      so it's worth a read of the license - it isn't scary!).  If you wish to
      contribute to Apache POI (which you're very welcome and encouraged to do so),
      then you must agree to grant your contributions to us under the same license.
    </p>
   </section>
  </section>

  <anchor id="WhereHelpNeeded"/>
  <section><title>Where is help needed on the project?</title>
    <p>There are a lot of open issues in Bugzilla and TODOs in the code. Please see
     the section below for more on these. Get in touch using our mailing lists if you want
     to volunteer.</p>
  </section>

  <anchor id="GetInvolved"/>
  <section><title>I just want to get involved, but don't know where to start?</title>
    <ul>
      <li>Read the rest of the website, understand what POI is and what it does,
          the project vision, etc.</li>
      <li>Use POI a bit, look for gaps in the documentation and examples.</li>
      <li>Join the <a href="site:mailinglists">mailing lists</a> and share your knowledge with others.</li>
      <li>Get <a href="site:git">Git</a> and check out the POI source tree</li>
      <li>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.</li>
      <li>Contribute examples - if there's something people are often asking about on the <a href="site:mailinglists">user list</a> which isn't covered in the documentation or current examples, try writing an example of this and uploading it as a patch.</li>
      <li>Get used to building POI, you'll be doing it a lot, be one with the build, know its targets, etc.</li>
      <li>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.</li>
      <li>Download the file format documentation from Microsoft -
        <a href="https://msdn.microsoft.com/en-us/library/cc313105%28v=office.12%29.aspx">OLE2 Binary
        File Formats</a> or
        <a href="https://ecma-international.org/publications-and-standards/standards/ecma-376/">OOXML XML File Formats</a></li>
      <li>Submit patches (see below) of your contributions, modifications.</li>
      <li>Check the <a href="https://issues.apache.org/bugzilla/buglist.cgi?product=POI">bug database</a> for simple problem reports, and write a patch to fix the problem</li>
      <li>Review existing patches in the <a href="http://issues.apache.org/bugzilla/buglist.cgi?product=POI">bug database</a>, and report if they still apply, if they need unit tests atc.</li>
      <li>Take a look at all the <a href="https://issues.apache.org/bugzilla/buglist.cgi?product=POI;bug_status=NEW;bug_status=NEEDINFO">unresolved issues in the bug database</a>, and see if you can help with testing or patches for them</li>
      <li>Add in new features, see <a href="https://issues.apache.org/bugzilla/buglist.cgi?product=POI">Bug database</a> for suggestions.</li>
    </ul>

    <p>The Apache <a href="https://infra.apache.org/contributors.html">Contributors Tech Guide</a> 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
     <a href="https://wiki.apache.org/nutch/Becoming_A_Nutch_Developer">http://wiki.apache.org/nutch/Becoming_A_Nutch_Developer</a>. The
     <a href="https://community.apache.org/">Apache Community Development
     Project</a> also provides guidance and mentoring for new contributors.</p>
   </section>

   <anchor id="SubmittingPatches"/>
   <section><title>Submitting Patches</title>
    <p>
      If you use GitHub, you can submit Pull Requests to https://github.com/apache/poi. It is probably
      a good idea to create an issue in the <a href="https://issues.apache.org/bugzilla/buglist.cgi?product=POI">Bug Database</a>
      first and reference it in the PR.
    </p>
    <p>
      You can add patch files to the Bugzilla issues at
      <a href="https://issues.apache.org/bugzilla/buglist.cgi?product=POI">Bug Database</a>.
      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.
      Explain you patch and any special instructions and submit/save it.
      Next, go back to the bug, and create attachments 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
      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 Git 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.
    </p>
    <p>
      A number of Apache projects provide far more comprehensive guides to producing
      and submitting patches than we do, you may wish to review some of their
      information if you're unsure. The
      <a href="https://commons.apache.org/patches.html">Apache Commons</a> one
      is fairly similar as a starting point.
    </p>
   <p>You may create your patch file using either of the following approaches (the committers recommend the first):</p>
     <section><title>Using Git</title>
     <p>
       If you are working on a Git clone of Apache POI (see the
       <a href="site:git">Version Control page</a> for
       more info), it is possible to generate
       a patch of your changes (including new binary files) using Git.
     </p>
     <p>
       When generating a patch / patch set from Git, for many related and
       small changes a squashed patch is probably best, as it makes the
       (manual) review quicker. For larger changes, several distinct
       patches are probably best.
     </p>
     <p>
       If you intend to do a noticeable amount of work enhancing Apache POI
       on your own Git repo, we would suggest sending in patches early and
       asking for advice. There's nothing worse than spending a week working
       hard on your own on a change, only to discover you did something on
       Day 1 that isn't acceptable to the project meaning your whole patch
       needs re-doing... Git's offline workflow makes this easier, so try not
       to fall into that trap!
     </p>
     </section>
     <section><title>checklist before submitting a patch</title>
       <ul>
         <li>Added code complies with <a href="#CodeStyle">coding standards</a>.</li>
         <li>Added code compiles and runs on Java 1.8 and preferably newer versions.</li>
         <li>New java files begin with the <a href="https://www.apache.org/foundation/license-faq.html">
              Apache Software License</a> statement.</li>
         <li>The code does not depend on code that is unlicensed or
         <a href="https://www.apache.org/legal/resolved.html#category-a">incompatibly licensed with ASL 2.0</a>.
         <a href="https://www.apache.org/licenses/GPL-compatibility.html">GPL</a> and LGPL code may not be used.</li>
         <li>The code does not include <code>@author</code> tags.</li>
         <li>Existing test cases succeed.</li>
         <li>New test cases written and succeed (Use <code>@Disabled</code> from <code>org.junit</code> for in-progress work).</li>
         <li>Documentation page extended as appropriate.</li>
         <li>Examples updated or added as appropriate.</li>
         <li>Diff files generated using <code>svn diff</code>.</li>
         <li>Newly added files are included in the patch or alongside the patch.</li>
         <li>The <a href="https://bz.apache.org/bugzilla/describecomponents.cgi?product=POI">bugzilla</a> subject dev contains [PATCH], task name and patch reason in subject.</li>
         <li>The bugzilla description contains a rationale for the patch.</li>
         <li>Attachment to the bugzilla entry contains the patch file.</li>
       </ul>
     </section>
   </section>

   <anchor id="CodeStyle"/>
   <section><title>Code Style</title>
     <p>The long standing
       <a href="site:res001">Minimal
       Coding Standards</a> from 2002 still largely apply to the project.</p>
     <p>When making changes to an existing file, please try to follow the
       same style that that file already uses. This will keep things
       looking similar, and will prevent patches becoming largely about
       whitespace. Whitespace fixing changes, if needed, should normally be
       in their own commit, so that they don't crowd out coding changes
       in review.</p>
     <p>Normally, tabs should not be used to indent code. Instead, spaces
       should be used. If starting on a fresh file, please use 4 spaces to
       indent your code. If working on an existing file, please use
       whichever of 3 or 4 spaces that file already follows.</p>
     <p>Normally, braces should open on the same line as the decision
       statement. Braces should normally close on their own line. Brackets
       should normally have a space before them when they are the first.</p>
     <p>Lines normally shouldn't be too long. There's no hard and fast rule,
       but if you line is getting above about 90 characters think about
       splitting it, and you should rarely create something over about 100
       characters without a very good reason!</p>
   </section>

   <anchor id="Mentoring"/>
   <section><title>Mentoring and Committership</title>
    <p>The POI project will generally offer committership to contributors who send
     in consistently good patches over a period of several months.</p>
    <p>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 <a href="site:mailinglists">dev mailing list</a>.</p>
    <p>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.</p>
    <p>Where possible, patches should be submitted early and often. For more details
     on this, please see the "Submitting Patches" section above.</p>

    <p>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
     <a href="site:mailinglists">dev mailing list</a> so that other
     contributors can assist you!</p>
    <p>For more information on getting started at Apache, mentoring, and local
     Apache Committers near you who can offer advice, please see the
     <a href="http://community.apache.org/">Apache Community Development
     Project</a> website.</p>
   </section>

  <anchor id="FileFormatInformation"/>
  <section><title>File Format Information</title>
   <section><title>Publicly Available Information on the file formats</title>
   <p>
    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 <a href="https://msdn.microsoft.com/en-us/openspecifications/default">
    Open Specification Promise</a>, which does allow us to use them for
    building open source software under the <a
      href="https://www.apache.org/foundation/license-FAQ.html">
    Apache Software License</a>.
   </p>
   <p>
    You can download the documentation on Excel, Word, PowerPoint and
    Escher (drawing) from
    <a href="https://msdn.microsoft.com/en-us/library/cc313118.aspx">http://msdn.microsoft.com/en-us/library/cc313118.aspx</a>.
    Documentation on a few of the supporting technologies used in these
    file formats can be downloaded from
    <a href="https://msdn.microsoft.com/en-us/library/jj633110.aspx">http://msdn.microsoft.com/en-us/library/jj633110.aspx</a>.
   </p>
   <p>
    For the VSDX format (implemented in Apache POI as XDGF), an
    <a href="https://msdn.microsoft.com/en-us/library/office/jj228622.aspx">introduction
    is available from Microsoft</a>, and full details are available
    <a href="https://msdn.microsoft.com/en-us/library/office/jj684209(v=office.15).aspx">here</a>
    and
    <a href="https://msdn.microsoft.com/en-us/library/hh645006(v=office.12).aspx">here</a>.
   </p>
   <p>
    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.
   </p>
   <p>
    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
    <a href="https://ecma-international.org/publications-and-standards/standards/ecma-376/">https://ecma-international.org/publications-and-standards/standards/ecma-376/</a>,
    and is also under the
    <a href="https://msdn.microsoft.com/en-us/openspecifications/default">OSP</a>.
   </p>
   <p>
    Additionally for the newer Office Open XML (ooxml) file formats, you can
    find some good introductary documentation (often clearer for getting
    started with) at <a href="http://officeopenxml.com/">officeopenxml.com</a>,
    which is an independent site documenting the file formats.
   </p>
   <p>
    It is also worth checking the documentation and code of the other
    open source implementations of the file formats.
   </p>
   </section>
   <section><title>I just signed an NDA to get a spec from Microsoft and I'd like to contribute</title>
    <p>
      In short, stay away, stay far far away.  Implementing these file formats
      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.
    </p>
    <p>
      If you've ever received information regarding the OLE 2 Compound Document
      Format under any type of exclusionary agreement from Microsoft, or
      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 publicly available. However, if you have
      been party to a Microsoft NDA, you will need to get clearance from Microsoft
      before contributing.
    </p>
    <p>
      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, and have only made us of the public documentation.
    </p>
   </section>
  </section>

 </body>
 <footer>
    <legal>
       Copyright (c) @year@ The Apache Software Foundation. All rights reserved.
       <br />
       Apache POI, POI, Apache, the Apache logo, and the Apache
       POI project logo are trademarks of The Apache Software Foundation.
    </legal>
 </footer>
 </document>
	<?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.
	====================================================================
	-->
	<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "document-v20.dtd">

	<document>
	<header>
	<title>Apache POI™ - Contribution Guidelines</title>
	<authors>
	<person name="Nick Burch" email="dev@poi.apache.org"/>
	<person name="David Fisher" email="dev@poi.apache.org"/>
	</authors>
	</header>

	<body>

	<section><title>Index of Contribution Guidelines</title>
	<ul>
	<li><a href="#Introduction">Introduction</a></li>
	<li><a href="#WhereHelpNeeded">Where is help needed on the project?</a></li>
	<li><a href="#GetInvolved">I just want to get involved, but don't know where to start?</a></li>
	<li><a href="#SubmittingPatches">Submitting Patches</a></li>
	<li><a href="#CodeStyle">Code Style</a></li>
	<li><a href="#Mentoring">Mentoring and Committership</a></li>
	<li><a href="#FileFormatInformation">File Format Information</a></li>
	</ul>
	</section>

	<anchor id="Introduction"/>
	<section><title>Introduction</title>

	<section><title>Disclaimer</title>
	<p>
	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.
	</p>
	</section>

	<section><title>The Licensing</title>
	<p>
	The POI project is <a href="http://www.opensource.org">OpenSource</a>
	and developed/distributed under the <a
	href="https://www.apache.org/foundation/license-faq.html">
	Apache Software License v2</a>. Unlike some other licenses, the Apache
	license allows free open source development. Unlike some other Open Source
	licenses, it does not require you to release your source or use any
	particular license for your code which builds on top of it. (There are a
	handful of restrictions, especially around attribution, notices and trademarks,
	so it's worth a read of the license - it isn't scary!). If you wish to
	contribute to Apache POI (which you're very welcome and encouraged to do so),
	then you must agree to grant your contributions to us under the same license.
	</p>
	</section>
	</section>

	<anchor id="WhereHelpNeeded"/>
	<section><title>Where is help needed on the project?</title>
	<p>There are a lot of open issues in Bugzilla and TODOs in the code. Please see
	the section below for more on these. Get in touch using our mailing lists if you want
	to volunteer.</p>
	</section>

	<anchor id="GetInvolved"/>
	<section><title>I just want to get involved, but don't know where to start?</title>
	<ul>
	<li>Read the rest of the website, understand what POI is and what it does,
	the project vision, etc.</li>
	<li>Use POI a bit, look for gaps in the documentation and examples.</li>
	<li>Join the <a href="site:mailinglists">mailing lists</a> and share your knowledge with others.</li>
	<li>Get <a href="site:git">Git</a> and check out the POI source tree</li>
	<li>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.</li>
	<li>Contribute examples - if there's something people are often asking about on the <a href="site:mailinglists">user list</a> which isn't covered in the documentation or current examples, try writing an example of this and uploading it as a patch.</li>
	<li>Get used to building POI, you'll be doing it a lot, be one with the build, know its targets, etc.</li>
	<li>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.</li>
	<li>Download the file format documentation from Microsoft -
	<a href="https://msdn.microsoft.com/en-us/library/cc313105%28v=office.12%29.aspx">OLE2 Binary
	File Formats</a> or
	<a href="https://ecma-international.org/publications-and-standards/standards/ecma-376/">OOXML XML File Formats</a></li>
	<li>Submit patches (see below) of your contributions, modifications.</li>
	<li>Check the <a href="https://issues.apache.org/bugzilla/buglist.cgi?product=POI">bug database</a> for simple problem reports, and write a patch to fix the problem</li>
	<li>Review existing patches in the <a href="http://issues.apache.org/bugzilla/buglist.cgi?product=POI">bug database</a>, and report if they still apply, if they need unit tests atc.</li>
	<li>Take a look at all the <a href="https://issues.apache.org/bugzilla/buglist.cgi?product=POI;bug_status=NEW;bug_status=NEEDINFO">unresolved issues in the bug database</a>, and see if you can help with testing or patches for them</li>
	<li>Add in new features, see <a href="https://issues.apache.org/bugzilla/buglist.cgi?product=POI">Bug database</a> for suggestions.</li>
	</ul>

	<p>The Apache <a href="https://infra.apache.org/contributors.html">Contributors Tech Guide</a> 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
	<a href="https://wiki.apache.org/nutch/Becoming_A_Nutch_Developer">http://wiki.apache.org/nutch/Becoming_A_Nutch_Developer</a>. The
	<a href="https://community.apache.org/">Apache Community Development
	Project</a> also provides guidance and mentoring for new contributors.</p>
	</section>

	<anchor id="SubmittingPatches"/>
	<section><title>Submitting Patches</title>
	<p>
	If you use GitHub, you can submit Pull Requests to https://github.com/apache/poi. It is probably
	a good idea to create an issue in the <a href="https://issues.apache.org/bugzilla/buglist.cgi?product=POI">Bug Database</a>
	first and reference it in the PR.
	</p>
	<p>
	You can add patch files to the Bugzilla issues at
	<a href="https://issues.apache.org/bugzilla/buglist.cgi?product=POI">Bug Database</a>.
	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.
	Explain you patch and any special instructions and submit/save it.
	Next, go back to the bug, and create attachments 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
	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 Git 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.
	</p>
	<p>
	A number of Apache projects provide far more comprehensive guides to producing
	and submitting patches than we do, you may wish to review some of their
	information if you're unsure. The
	<a href="https://commons.apache.org/patches.html">Apache Commons</a> one
	is fairly similar as a starting point.
	</p>
	<p>You may create your patch file using either of the following approaches (the committers recommend the first):</p>
	<section><title>Using Git</title>
	<p>
	If you are working on a Git clone of Apache POI (see the
	<a href="site:git">Version Control page</a> for
	more info), it is possible to generate
	a patch of your changes (including new binary files) using Git.
	</p>
	<p>
	When generating a patch / patch set from Git, for many related and
	small changes a squashed patch is probably best, as it makes the
	(manual) review quicker. For larger changes, several distinct
	patches are probably best.
	</p>
	<p>
	If you intend to do a noticeable amount of work enhancing Apache POI
	on your own Git repo, we would suggest sending in patches early and
	asking for advice. There's nothing worse than spending a week working
	hard on your own on a change, only to discover you did something on
	Day 1 that isn't acceptable to the project meaning your whole patch
	needs re-doing... Git's offline workflow makes this easier, so try not
	to fall into that trap!
	</p>
	</section>
	<section><title>checklist before submitting a patch</title>
	<ul>
	<li>Added code complies with <a href="#CodeStyle">coding standards</a>.</li>
	<li>Added code compiles and runs on Java 1.8 and preferably newer versions.</li>
	<li>New java files begin with the <a href="https://www.apache.org/foundation/license-faq.html">
	Apache Software License</a> statement.</li>
	<li>The code does not depend on code that is unlicensed or
	<a href="https://www.apache.org/legal/resolved.html#category-a">incompatibly licensed with ASL 2.0</a>.
	<a href="https://www.apache.org/licenses/GPL-compatibility.html">GPL</a> and LGPL code may not be used.</li>
	<li>The code does not include <code>@author</code> tags.</li>
	<li>Existing test cases succeed.</li>
	<li>New test cases written and succeed (Use <code>@Disabled</code> from <code>org.junit</code> for in-progress work).</li>
	<li>Documentation page extended as appropriate.</li>
	<li>Examples updated or added as appropriate.</li>
	<li>Diff files generated using <code>svn diff</code>.</li>
	<li>Newly added files are included in the patch or alongside the patch.</li>
	<li>The <a href="https://bz.apache.org/bugzilla/describecomponents.cgi?product=POI">bugzilla</a> subject dev contains [PATCH], task name and patch reason in subject.</li>
	<li>The bugzilla description contains a rationale for the patch.</li>
	<li>Attachment to the bugzilla entry contains the patch file.</li>
	</ul>
	</section>
	</section>

	<anchor id="CodeStyle"/>
	<section><title>Code Style</title>
	<p>The long standing
	<a href="site:res001">Minimal
	Coding Standards</a> from 2002 still largely apply to the project.</p>
	<p>When making changes to an existing file, please try to follow the
	same style that that file already uses. This will keep things
	looking similar, and will prevent patches becoming largely about
	whitespace. Whitespace fixing changes, if needed, should normally be
	in their own commit, so that they don't crowd out coding changes
	in review.</p>
	<p>Normally, tabs should not be used to indent code. Instead, spaces
	should be used. If starting on a fresh file, please use 4 spaces to
	indent your code. If working on an existing file, please use
	whichever of 3 or 4 spaces that file already follows.</p>
	<p>Normally, braces should open on the same line as the decision
	statement. Braces should normally close on their own line. Brackets
	should normally have a space before them when they are the first.</p>
	<p>Lines normally shouldn't be too long. There's no hard and fast rule,
	but if you line is getting above about 90 characters think about
	splitting it, and you should rarely create something over about 100
	characters without a very good reason!</p>
	</section>

	<anchor id="Mentoring"/>
	<section><title>Mentoring and Committership</title>
	<p>The POI project will generally offer committership to contributors who send
	in consistently good patches over a period of several months.</p>
	<p>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 <a href="site:mailinglists">dev mailing list</a>.</p>
	<p>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.</p>
	<p>Where possible, patches should be submitted early and often. For more details
	on this, please see the "Submitting Patches" section above.</p>

	<p>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
	<a href="site:mailinglists">dev mailing list</a> so that other
	contributors can assist you!</p>
	<p>For more information on getting started at Apache, mentoring, and local
	Apache Committers near you who can offer advice, please see the
	<a href="http://community.apache.org/">Apache Community Development
	Project</a> website.</p>
	</section>

	<anchor id="FileFormatInformation"/>
	<section><title>File Format Information</title>
	<section><title>Publicly Available Information on the file formats</title>
	<p>
	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 <a href="https://msdn.microsoft.com/en-us/openspecifications/default">
	Open Specification Promise</a>, which does allow us to use them for
	building open source software under the <a
	href="https://www.apache.org/foundation/license-FAQ.html">
	Apache Software License</a>.
	</p>
	<p>
	You can download the documentation on Excel, Word, PowerPoint and
	Escher (drawing) from
	<a href="https://msdn.microsoft.com/en-us/library/cc313118.aspx">http://msdn.microsoft.com/en-us/library/cc313118.aspx</a>.
	Documentation on a few of the supporting technologies used in these
	file formats can be downloaded from
	<a href="https://msdn.microsoft.com/en-us/library/jj633110.aspx">http://msdn.microsoft.com/en-us/library/jj633110.aspx</a>.
	</p>
	<p>
	For the VSDX format (implemented in Apache POI as XDGF), an
	<a href="https://msdn.microsoft.com/en-us/library/office/jj228622.aspx">introduction
	is available from Microsoft</a>, and full details are available
	<a href="https://msdn.microsoft.com/en-us/library/office/jj684209(v=office.15).aspx">here</a>
	and
	<a href="https://msdn.microsoft.com/en-us/library/hh645006(v=office.12).aspx">here</a>.
	</p>
	<p>
	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.
	</p>
	<p>
	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
	<a href="https://ecma-international.org/publications-and-standards/standards/ecma-376/">https://ecma-international.org/publications-and-standards/standards/ecma-376/</a>,
	and is also under the
	<a href="https://msdn.microsoft.com/en-us/openspecifications/default">OSP</a>.
	</p>
	<p>
	Additionally for the newer Office Open XML (ooxml) file formats, you can
	find some good introductary documentation (often clearer for getting
	started with) at <a href="http://officeopenxml.com/">officeopenxml.com</a>,
	which is an independent site documenting the file formats.
	</p>
	<p>
	It is also worth checking the documentation and code of the other
	open source implementations of the file formats.
	</p>
	</section>
	<section><title>I just signed an NDA to get a spec from Microsoft and I'd like to contribute</title>
	<p>
	In short, stay away, stay far far away. Implementing these file formats
	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.
	</p>
	<p>
	If you've ever received information regarding the OLE 2 Compound Document
	Format under any type of exclusionary agreement from Microsoft, or
	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 publicly available. However, if you have
	been party to a Microsoft NDA, you will need to get clearance from Microsoft
	before contributing.
	</p>
	<p>
	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, and have only made us of the public documentation.
	</p>
	</section>
	</section>

	</body>
	<footer>
	<legal>
	Copyright (c) @year@ The Apache Software Foundation. All rights reserved.
	<br />
	Apache POI, POI, Apache, the Apache logo, and the Apache
	POI project logo are trademarks of The Apache Software Foundation.
	</legal>
	</footer>
	</document>