src/documentation/content/xdocs/getinvolved/index.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 V1.1//EN" "./dtd/document-v11.dtd">

 <document>
  <header>
   <title>Contribution to POI</title>
   <authors>
    <person name="Nicola Ken Barozzi" email="barozzi@nicolaken.com"/>
    <person name="Marc Johnson" email="mjohnson@apache.org"/>
    <person name="Andrew C. Oliver" email="acoliver@apache.org"/>
    <person name="Tetsuya Kitahata" email="tetsuya.kitahata@nifty.com"/>
    </authors>
  </header>

  <body>

  <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 <link href="http://www.opensource.org">OpenSource</link>
      and developed/distributed under the <link
      href="http://www.apache.org/foundation/licence-FAQ.html">
      Apache Software License</link>.  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.
    </p>
   </section>
   <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 <link href="http://www.microsoft.com/interop/osp">Open
    Specification Promise</link>, which does allow us to use them for
    building open source software under the <link
      href="http://www.apache.org/foundation/licence-FAQ.html">
    Apache Software License</link>.
   </p>
   <p>
    You can download the documentation on Excel, Word, PowerPoint and
    Escher (drawing) from
    <link href="http://www.microsoft.com/interop/docs/OfficeBinaryFormats.mspx">http://www.microsoft.com/interop/docs/OfficeBinaryFormats.mspx</link>.
    Documentation on a few of the supporting technologies used in these
    file formats can be downloaded from
    <link href="http://www.microsoft.com/interop/docs/supportingtechnologies.mspx">http://www.microsoft.com/interop/docs/supportingtechnologies.mspx</link>.
   </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
    <link href="http://www.ecma-international.org/publications/standards/Ecma-376.htm">http://www.ecma-international.org/publications/standards/Ecma-376.htm</link>,
    and is also under the <link href="http://www.microsoft.com/interop/osp">OSP</link>.
   </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.  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
      (possibly illegally) received such information from a person bound by
      such an agreement, you cannot participate in this project. (Sorry)
    </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.
    </p>
   </section>
  </section>
   <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 mail lists and share your knowledge with others.</li>
      <li>Get <link href="../subversion.html">Subversion</link> 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>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 -
       <link href="http://www.microsoft.com/interop/docs/OfficeBinaryFormats.mspx">OLE2 Binary File Formats</link> or
       <link href="http://www.ecma-international.org/publications/standards/Ecma-376.htm">OOXML XML File Formats</link></li>
      <li>Submit patches (see below) of your contributions, modifications.</li>
      <li>Fill out new features, see <link href="http://issues.apache.org/bugzilla/buglist.cgi?product=POI">Bug database</link> for suggestions.</li>
    </ul>
   </section>
   <section><title>Submitting Patches</title>
    <p>
      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.
    </p>
    <p>
      Patches are submitted via the <link href="http://issues.apache.org/bugzilla/buglist.cgi?product=POI">Bug Database</link>.
      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?).
    </p>
    <p>
      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
      <link href="http://poi.apache.org/resolutions/res001.html">Coding
      Standards</link>).  Patches that are of low quality may be rejected or
      the contributer may be asked to bring them up to spec.
    </p>
    <p>If you use a unix shell, you may find the following following
     sequence of commands useful for building the files to attach.</p>
    <source>
 # 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"
    </source>
   </section>

 </body>
 </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 V1.1//EN" "./dtd/document-v11.dtd">

	<document>
	<header>
	<title>Contribution to POI</title>
	<authors>
	<person name="Nicola Ken Barozzi" email="barozzi@nicolaken.com"/>
	<person name="Marc Johnson" email="mjohnson@apache.org"/>
	<person name="Andrew C. Oliver" email="acoliver@apache.org"/>
	<person name="Tetsuya Kitahata" email="tetsuya.kitahata@nifty.com"/>
	</authors>
	</header>

	<body>

	<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 <link href="http://www.opensource.org">OpenSource</link>
	and developed/distributed under the <link
	href="http://www.apache.org/foundation/licence-FAQ.html">
	Apache Software License</link>. 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.
	</p>
	</section>
	<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 <link href="http://www.microsoft.com/interop/osp">Open
	Specification Promise</link>, which does allow us to use them for
	building open source software under the <link
	href="http://www.apache.org/foundation/licence-FAQ.html">
	Apache Software License</link>.
	</p>
	<p>
	You can download the documentation on Excel, Word, PowerPoint and
	Escher (drawing) from
	<link href="http://www.microsoft.com/interop/docs/OfficeBinaryFormats.mspx">http://www.microsoft.com/interop/docs/OfficeBinaryFormats.mspx</link>.
	Documentation on a few of the supporting technologies used in these
	file formats can be downloaded from
	<link href="http://www.microsoft.com/interop/docs/supportingtechnologies.mspx">http://www.microsoft.com/interop/docs/supportingtechnologies.mspx</link>.
	</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
	<link href="http://www.ecma-international.org/publications/standards/Ecma-376.htm">http://www.ecma-international.org/publications/standards/Ecma-376.htm</link>,
	and is also under the <link href="http://www.microsoft.com/interop/osp">OSP</link>.
	</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. 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
	(possibly illegally) received such information from a person bound by
	such an agreement, you cannot participate in this project. (Sorry)
	</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.
	</p>
	</section>
	</section>
	<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 mail lists and share your knowledge with others.</li>
	<li>Get <link href="../subversion.html">Subversion</link> 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>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 -
	<link href="http://www.microsoft.com/interop/docs/OfficeBinaryFormats.mspx">OLE2 Binary File Formats</link> or
	<link href="http://www.ecma-international.org/publications/standards/Ecma-376.htm">OOXML XML File Formats</link></li>
	<li>Submit patches (see below) of your contributions, modifications.</li>
	<li>Fill out new features, see <link href="http://issues.apache.org/bugzilla/buglist.cgi?product=POI">Bug database</link> for suggestions.</li>
	</ul>
	</section>
	<section><title>Submitting Patches</title>
	<p>
	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.
	</p>
	<p>
	Patches are submitted via the <link href="http://issues.apache.org/bugzilla/buglist.cgi?product=POI">Bug Database</link>.
	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?).
	</p>
	<p>
	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
	<link href="http://poi.apache.org/resolutions/res001.html">Coding
	Standards</link>). Patches that are of low quality may be rejected or
	the contributer may be asked to bring them up to spec.
	</p>
	<p>If you use a unix shell, you may find the following following
	sequence of commands useful for building the files to attach.</p>
	<source>
	# 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"
	</source>
	</section>

	</body>
	</document>