src/documentation/content/xdocs/getinvolved/index.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!--
   3    ====================================================================
   4    Licensed to the Apache Software Foundation (ASF) under one or more
   5    contributor license agreements.  See the NOTICE file distributed with
   6    this work for additional information regarding copyright ownership.
   7    The ASF licenses this file to You under the Apache License, Version 2.0
   8    (the "License"); you may not use this file except in compliance with
   9    the License.  You may obtain a copy of the License at
  10
  11        http://www.apache.org/licenses/LICENSE-2.0
  12
  13    Unless required by applicable law or agreed to in writing, software
  14    distributed under the License is distributed on an "AS IS" BASIS,
  15    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  16    See the License for the specific language governing permissions and
  17    limitations under the License.
  18    ====================================================================
  19 -->
  20 <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "./dtd/document-v11.dtd">
  21
  22 <document>
  23  <header>
  24   <title>Contribution to POI</title>
  25   <authors>
  26    <person name="Nicola Ken Barozzi" email="barozzi@nicolaken.com"/>
  27    <person name="Marc Johnson" email="mjohnson@apache.org"/>
  28    <person name="Andrew C. Oliver" email="acoliver@apache.org"/>
  29    <person name="Tetsuya Kitahata" email="tetsuya.kitahata@nifty.com"/>
  30    </authors>
  31  </header>
  32
  33  <body>
  34
  35  <section><title>Introduction</title>
  36   <section><title>Disclaimer</title>
  37    <p>
  38      Any information in here that might be perceived as legal information is
  39      informational only.  We're not lawyers, so consult a legal professional
  40      if needed.
  41    </p>
  42   </section>
  43   <section><title>The Licensing</title>
  44    <p>
  45      The POI project is <link href="http://www.opensource.org">OpenSource</link>
  46      and developed/distributed under the <link
  47      href="http://www.apache.org/foundation/licence-FAQ.html">
  48      Apache Software License</link>.  Unlike other licenses this license allows
  49      free open source development; however, it does not require you to release
  50      your source or use any particular license for your source.  If you wish
  51      to contribute to POI (which you're very welcome and encouraged to do so)
  52      then you must agree to release the rights of your source to us under this
  53      license.
  54    </p>
  55   </section>
  56   <section><title>Publicly Available Information on the file formats</title>
  57   <p>
  58    In early 2008, Microsoft made a fairly complete set of documentation
  59    on the binary file formats freely and publicly available. These were
  60    released under the <link href="http://www.microsoft.com/interop/osp">Open
  61    Specification Promise</link>, which does allow us to use them for
  62    building open source software under the <link
  63      href="http://www.apache.org/foundation/licence-FAQ.html">
  64    Apache Software License</link>.
  65   </p>
  66   <p>
  67    You can download the documentation on Excel, Word, PowerPoint and
  68    Escher (drawing) from
  69    <link href="http://www.microsoft.com/interop/docs/OfficeBinaryFormats.mspx">http://www.microsoft.com/interop/docs/OfficeBinaryFormats.mspx</link>.
  70    Documentation on a few of the supporting technologies used in these
  71    file formats can be downloaded from
  72    <link href="http://www.microsoft.com/interop/docs/supportingtechnologies.mspx">http://www.microsoft.com/interop/docs/supportingtechnologies.mspx</link>.
  73   </p>
  74   <p>
  75    Previously, Microsoft published a book on the Excel 97 file format.
  76    It can still be of plenty of use, and is handy dead tree form. Pick up
  77    a copy of "Excel 97 Developer's Kit" from your favourite second hand
  78    book store.
  79   </p>
  80   <p>
  81    The newer Office Open XML (ooxml) file formats are documented as part
  82    of the ECMA / ISO standardisation effort for the formats. This
  83    documentation is quite large, but you can normally find the bit you
  84    need without too much effort! This can be downloaded from
  85    <link href="http://www.ecma-international.org/publications/standards/Ecma-376.htm">http://www.ecma-international.org/publications/standards/Ecma-376.htm</link>,
  86    and is also under the <link href="http://www.microsoft.com/interop/osp">OSP</link>.
  87   </p>
  88   <p>
  89    It is also worth checking the documentation and code of the other
  90    open source implementations of the file formats.
  91   </p>
  92   </section>
  93   <section><title>I just signed an NDA to get a spec from Microsoft and I'd like to contribute</title>
  94    <p>
  95      In short, stay away, stay far far away.  Implementing these file formats
  96      in POI is done strictly by using public information.  Public information
  97      includes sources from other open source projects, books that state the
  98      purpose intended is for allowing implementation of the file format and
  99      do not require any non-disclosure agreement and just hard work.
 100      We are intent on keeping it
 101      legal, by contributing patches you agree to do the same.
 102    </p>
 103    <p>
 104      If you've ever received information regarding the OLE 2 Compound Document
 105      Format under any type of exclusionary agreement from Microsoft, or
 106      (possibly illegally) received such information from a person bound by
 107      such an agreement, you cannot participate in this project. (Sorry)
 108    </p>
 109    <p>
 110      Those submitting patches that show insight into the file format may be
 111      asked to state explicitly that they have only ever read the publicly
 112      available file format information, and not any received under an NDA
 113      or similar.
 114    </p>
 115   </section>
 116  </section>
 117   <section><title>I just want to get involved but don't know where to start</title>
 118    <ul>
 119      <li>Read the rest of the website, understand what POI is and what it does,
 120          the project vision, etc.</li>
 121      <li>Use POI a bit, look for gaps in the documentation and examples.</li>
 122      <li>Join the mail lists and share your knowledge with others.</li>
 123      <li>Get <link href="../subversion.html">Subversion</link> and check out the POI source tree</li>
 124      <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>
 125      <li>Get used to building POI, you'll be doing it a lot, be one with the build, know its targets, etc.</li>
 126      <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>
 127      <li>Download the file format documentation from Microsoft -
 128       <link href="http://www.microsoft.com/interop/docs/OfficeBinaryFormats.mspx">OLE2 Binary File Formats</link> or
 129       <link href="http://www.ecma-international.org/publications/standards/Ecma-376.htm">OOXML XML File Formats</link></li>
 130      <li>Submit patches (see below) of your contributions, modifications.</li>
 131      <li>Fill out new features, see <link href="http://issues.apache.org/bugzilla/buglist.cgi?product=POI">Bug database</link> for suggestions.</li>
 132    </ul>
 133   </section>
 134   <section><title>Submitting Patches</title>
 135    <p>
 136      Create patches by getting the latest sources from Subversion.
 137      Alter or add files as appropriate.  Then, from the poi directiory,
 138      type svn diff > mypatch.patch.  This will capture all of your changes
 139      in a patch file of the appropriate format. However, svn diff won't
 140      capture any new files you may have added. So, if you've added any
 141      files, create an archive (tar.bz2 preferred as its the smallest) in a
 142      path-preserving archive format, relative to your poi directory.
 143      You'll attach both files in the next step.
 144    </p>
 145    <p>
 146      Patches are submitted via the <link href="http://issues.apache.org/bugzilla/buglist.cgi?product=POI">Bug Database</link>.
 147      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.
 148      Next, go back to the bug, and create attachements for the patch files you
 149      created.  Be sure to describe not only the files purpose, but its format.
 150      (Is that ZIP or a tgz or a bz2 or what?).
 151    </p>
 152    <p>
 153      Make sure your patches include the @author tag on any files you've altered
 154      or created.  Make sure you've documented your changes and altered the
 155      examples/etc to reflect them.  Any new additions should have unit tests.
 156      Lastly, ensure that you've provided approriate javadoc.  (see
 157      <link href="http://poi.apache.org/resolutions/res001.html">Coding
 158      Standards</link>).  Patches that are of low quality may be rejected or
 159      the contributer may be asked to bring them up to spec.
 160    </p>
 161    <p>If you use a unix shell, you may find the following following
 162     sequence of commands useful for building the files to attach.</p>
 163    <source>
 164 # Run this in the root of the checkout, i.e. the directory holding
 165 #  build.xml and poi.pom
 166
 167 # Build the directory to hold new files
 168 mkdir /tmp/poi-patch/
 169 mkdir /tmp/poi-patch/new-files/
 170
 171 # Get changes to existing files
 172 svn diff > /tmp/poi-patch/diff.txt
 173
 174 # Capture any new files, as svn diff won't include them
 175 # Preserve the path
 176 svn status | grep "^\?" | awk '{printf "cp --parents %s /tmp/poi-patch/new-files/\n", $2 }' | sh -s
 177
 178 # tar up the new files
 179 cd /tmp/poi-patch/new-files/
 180 tar jcvf ../new-files.tar.bz2
 181 cd ..
 182
 183 # Upload these to bugzilla
 184 echo "Please upload to bugzilla:"
 185 echo "   /tmp/poi-patch/diff.txt"
 186 echo "   /tmp/poi-patch/new-files.tar.bz2"
 187    </source>
 188   </section>
 189
 190 </body>
 191 </document>