mirror of
https://github.com/apache/poi.git
synced 2026-02-27 20:40:08 +08:00
607 lines
26 KiB
HTML
607 lines
26 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
|
|
<html>
|
|
<head>
|
|
<META http-equiv="Content-Type" content="text/html; charset=UTF-8">
|
|
<meta content="Apache Forrest" name="Generator">
|
|
<meta name="Forrest-version" content="0.9">
|
|
<meta name="Forrest-skin-name" content="pelt">
|
|
<title>Apache POI™ - Contribution Guidelines</title>
|
|
<link type="text/css" href="../skin/basic.css" rel="stylesheet">
|
|
<link media="screen" type="text/css" href="../skin/screen.css" rel="stylesheet">
|
|
<link media="print" type="text/css" href="../skin/print.css" rel="stylesheet">
|
|
<link type="text/css" href="../skin/profile.css" rel="stylesheet">
|
|
<script src="../skin/getBlank.js" language="javascript" type="text/javascript"></script><script src="../skin/getMenu.js" language="javascript" type="text/javascript"></script><script src="../skin/fontsize.js" language="javascript" type="text/javascript"></script>
|
|
<link rel="shortcut icon" href="../images/favicon.ico">
|
|
</head>
|
|
<body onload="init()">
|
|
<script type="text/javascript">ndeSetTextSize();</script>
|
|
<div id="top">
|
|
<!--+
|
|
|breadtrail
|
|
+-->
|
|
<div class="breadtrail">
|
|
<a href="https://www.apache.org">Apache Software Foundation</a> > <a href="https://poi.apache.org">Apache POI</a><script src="../skin/breadcrumbs.js" language="JavaScript" type="text/javascript"></script>
|
|
</div>
|
|
<!--+
|
|
|header
|
|
+-->
|
|
<div class="header">
|
|
<!--+
|
|
|start group logo
|
|
+-->
|
|
<div class="grouplogo">
|
|
<a href="https://www.apache.org"><img class="logoImage" alt="Apache Software Foundation" src="../images/asflogo_horizontal_color.svg" title="The Apache Software Foundation is a cornerstone of the modern Open Source software ecosystem – supporting some of the most widely used and important software solutions powering today's Internet economy."></a>
|
|
</div>
|
|
<!--+
|
|
|end group logo
|
|
+-->
|
|
<!--+
|
|
|start Project Logo
|
|
+-->
|
|
<div class="projectlogo">
|
|
<a href="https://poi.apache.org"><img class="logoImage" alt="Apache POI" src="../images/project-header.png" title="Apache POI is well-known in the Java field as a library for reading and writing Microsoft Office file formats, such as Excel, PowerPoint, Word, Visio, Publisher and Outlook. It supports both the older (OLE2) and new (OOXML - Office Open XML) formats."></a>
|
|
</div>
|
|
<!--+
|
|
|end Project Logo
|
|
+-->
|
|
<!--+
|
|
|start Search
|
|
+-->
|
|
<div class="searchbox">
|
|
<form action="https://www.google.com/search" method="get" class="roundtopsmall">
|
|
<input value="poi.apache.org" name="sitesearch" type="hidden"><input onFocus="getBlank (this, 'Search the site with google');" size="25" name="q" id="query" type="text" value="Search the site with google">
|
|
<input name="Search" value="Search" type="submit">
|
|
</form>
|
|
</div>
|
|
<!--+
|
|
|end search
|
|
+-->
|
|
<!--+
|
|
|start Tabs
|
|
+-->
|
|
<ul id="tabs">
|
|
<li>
|
|
<a class="unselected" href="../index.html">Home</a>
|
|
</li>
|
|
<li>
|
|
<a class="unselected" href="../help/index.html">Help</a>
|
|
</li>
|
|
<li>
|
|
<a class="unselected" href="../components/index.html">Component APIs</a>
|
|
</li>
|
|
<li class="current">
|
|
<a class="selected" href="../devel/index.html">Getting Involved</a>
|
|
</li>
|
|
</ul>
|
|
<!--+
|
|
|end Tabs
|
|
+-->
|
|
</div>
|
|
</div>
|
|
<div id="main">
|
|
<div id="publishedStrip">
|
|
<!--+
|
|
|start Subtabs
|
|
+-->
|
|
<div id="level2tabs"></div>
|
|
<!--+
|
|
|end Endtabs
|
|
+-->
|
|
<script type="text/javascript"><!--
|
|
document.write("Last Published: " + document.lastModified);
|
|
// --></script>
|
|
</div>
|
|
<!--+
|
|
|breadtrail
|
|
+-->
|
|
<div class="breadtrail">
|
|
|
|
|
|
</div>
|
|
<!--+
|
|
|start Menu, mainarea
|
|
+-->
|
|
<!--+
|
|
|start Menu
|
|
+-->
|
|
<div id="menu">
|
|
<div onclick="SwitchMenu('menu_selected_1.1', '../skin/')" id="menu_selected_1.1Title" class="menutitle" style="background-image: url('../skin/images/chapter_open.gif');">Getting Involved</div>
|
|
<div id="menu_selected_1.1" class="selectedmenuitemgroup" style="display: block;">
|
|
<div class="menuitem">
|
|
<a href="../devel/index.html">How To Build</a>
|
|
</div>
|
|
<div class="menuitem">
|
|
<a href="../devel/nightly.html">Nightly Builds</a>
|
|
</div>
|
|
<div class="menuitem">
|
|
<a href="../devel/git.html">Git Repository</a>
|
|
</div>
|
|
<div class="menupage">
|
|
<div class="menupagetitle">Contribution Guidelines</div>
|
|
</div>
|
|
<div class="menuitem">
|
|
<a href="../devel/who.html">Who We Are</a>
|
|
</div>
|
|
<div onclick="SwitchMenu('menu_1.1.6', '../skin/')" id="menu_1.1.6Title" class="menutitle">Planning Documents</div>
|
|
<div id="menu_1.1.6" class="menuitemgroup">
|
|
<div class="menuitem">
|
|
<a href="../devel/plan/index.html">Overview</a>
|
|
</div>
|
|
<div class="menuitem">
|
|
<a href="../devel/plan/vision10.html">1.0 Vision</a>
|
|
</div>
|
|
<div class="menuitem">
|
|
<a href="../devel/plan/vision20.html">2.0 Vision</a>
|
|
</div>
|
|
</div>
|
|
<div onclick="SwitchMenu('menu_1.1.7', '../skin/')" id="menu_1.1.7Title" class="menutitle">References</div>
|
|
<div id="menu_1.1.7" class="menuitemgroup">
|
|
<div class="menuitem">
|
|
<a href="../devel/references/index.html">Overview</a>
|
|
</div>
|
|
<div class="menuitem">
|
|
<a href="../devel/references/logocontest.html">Logo Submissions</a>
|
|
</div>
|
|
<div class="menuitem">
|
|
<a href="https://sc.openoffice.org/excelfileformat.pdf">XLS spec [PDF]</a>
|
|
</div>
|
|
<div class="menuitem">
|
|
<a href="https://xml.apache.org/cocoon/">Apache Cocoon</a>
|
|
</div>
|
|
</div>
|
|
<div onclick="SwitchMenu('menu_1.1.8', '../skin/')" id="menu_1.1.8Title" class="menutitle">Resolutions</div>
|
|
<div id="menu_1.1.8" class="menuitemgroup">
|
|
<div class="menuitem">
|
|
<a href="../devel/resolutions/index.html">Overview</a>
|
|
</div>
|
|
<div class="menuitem">
|
|
<a href="../devel/resolutions/res001.html">Minimal Coding Standards</a>
|
|
</div>
|
|
</div>
|
|
<div onclick="SwitchMenu('menu_1.1.9', '../skin/')" id="menu_1.1.9Title" class="menutitle">History</div>
|
|
<div id="menu_1.1.9" class="menuitemgroup">
|
|
<div class="menuitem">
|
|
<a href="../devel/history/index.html">The early years</a>
|
|
</div>
|
|
<div class="menuitem">
|
|
<a href="../devel/history/changes-3x.html">Changelog 3.x</a>
|
|
</div>
|
|
<div class="menuitem">
|
|
<a href="../devel/history/changes-pre3x.html">Changelog 0-2.x</a>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div id="credit"></div>
|
|
<div id="roundbottom">
|
|
<img style="display: none" class="corner" height="15" width="15" alt="" src="../skin/images/rc-b-l-15-1body-2menu-3menu.png"></div>
|
|
<!--+
|
|
|alternative credits
|
|
+-->
|
|
<div id="credit2">
|
|
<a href="https://donate.apache.org/"><img border="0" title="Support Apache" alt="Support Apache - logo" src="../images/support-asf.png" style="width: 125px;height: 125px;"></a><a href="https://www.apache.org/foundation/press/kit/#poweredby"><img border="0" title="powered by POI" alt="powered by POI - logo" src="../images/poweredby-poi-logo.png" style="width: 125px;height: 125px;"></a>
|
|
</div>
|
|
</div>
|
|
<!--+
|
|
|end Menu
|
|
+-->
|
|
<!--+
|
|
|start content
|
|
+-->
|
|
<div id="content">
|
|
<h1>Apache POI™ - Contribution Guidelines</h1>
|
|
<div id="front-matter"></div>
|
|
|
|
|
|
<a name="Index+of+Contribution+Guidelines"></a>
|
|
<h2 class="boxed">Index of Contribution Guidelines</h2>
|
|
<div class="section">
|
|
<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>
|
|
</div>
|
|
|
|
|
|
<a name="Introduction" id="Introduction"></a>
|
|
<a name="Introduction-N10048"></a>
|
|
<h2 class="boxed">Introduction</h2>
|
|
<div class="section">
|
|
<a name="Disclaimer"></a>
|
|
<h3 class="boxed">Disclaimer</h3>
|
|
<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>
|
|
<a name="The+Licensing"></a>
|
|
<h3 class="boxed">The Licensing</h3>
|
|
<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>
|
|
</div>
|
|
|
|
|
|
<a name="WhereHelpNeeded" id="WhereHelpNeeded"></a>
|
|
<a name="Where+is+help+needed+on+the+project%3F"></a>
|
|
<h2 class="boxed">Where is help needed on the project?</h2>
|
|
<div class="section">
|
|
<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>
|
|
</div>
|
|
|
|
|
|
<a name="GetInvolved" id="GetInvolved"></a>
|
|
<a name="I+just+want+to+get+involved%2C+but+don%27t+know+where+to+start%3F"></a>
|
|
<h2 class="boxed">I just want to get involved, but don't know where to start?</h2>
|
|
<div class="section">
|
|
<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="../help/index.html">mailing lists</a> and share your knowledge with others.</li>
|
|
|
|
<li>Get <a href="../devel/git.html">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="../help/index.html">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>
|
|
</div>
|
|
|
|
|
|
<a name="SubmittingPatches" id="SubmittingPatches"></a>
|
|
<a name="Submitting+Patches"></a>
|
|
<h2 class="boxed">Submitting Patches</h2>
|
|
<div class="section">
|
|
<p>
|
|
If you use GitHub, you can submit Pull Requests to <a href="https://github.com/apache/poi">https://github.com/apache/poi</a>.
|
|
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>
|
|
<a name="Using+Git"></a>
|
|
<h3 class="boxed">Using Git</h3>
|
|
<p>
|
|
If you are working on a Git clone of Apache POI (see the
|
|
<a href="../devel/git.html">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>
|
|
<a name="checklist+before+submitting+a+patch"></a>
|
|
<h3 class="boxed">checklist before submitting a patch</h3>
|
|
<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 <span class="codefrag">@author</span> tags.</li>
|
|
|
|
<li>Existing test cases succeed.</li>
|
|
|
|
<li>New test cases written and succeed (Use <span class="codefrag">@Disabled</span> from <span class="codefrag">org.junit</span> 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 <span class="codefrag">svn diff</span>.</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>
|
|
</div>
|
|
|
|
|
|
<a name="CodeStyle" id="CodeStyle"></a>
|
|
<a name="Code+Style"></a>
|
|
<h2 class="boxed">Code Style</h2>
|
|
<div class="section">
|
|
<p>The long standing
|
|
<a href="../devel/resolutions/res001.html">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>
|
|
</div>
|
|
|
|
|
|
<a name="Mentoring" id="Mentoring"></a>
|
|
<a name="Mentoring+and+Committership"></a>
|
|
<h2 class="boxed">Mentoring and Committership</h2>
|
|
<div class="section">
|
|
<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="../help/index.html">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="../help/index.html">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>
|
|
</div>
|
|
|
|
|
|
<a name="FileFormatInformation" id="FileFormatInformation"></a>
|
|
<a name="File+Format+Information"></a>
|
|
<h2 class="boxed">File Format Information</h2>
|
|
<div class="section">
|
|
<a name="Publicly+Available+Information+on+the+file+formats"></a>
|
|
<h3 class="boxed">Publicly Available Information on the file formats</h3>
|
|
<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>
|
|
<a name="I+just+signed+an+NDA+to+get+a+spec+from+Microsoft+and+I%27d+like+to+contribute"></a>
|
|
<h3 class="boxed">I just signed an NDA to get a spec from Microsoft and I'd like to contribute</h3>
|
|
<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>
|
|
</div>
|
|
|
|
|
|
<p align="right">
|
|
<font size="-2">by Nick Burch, David Fisher</font>
|
|
</p>
|
|
</div>
|
|
<!--+
|
|
|end content
|
|
+-->
|
|
<div class="clearboth"> </div>
|
|
</div>
|
|
<div id="footer">
|
|
<!--+
|
|
|start bottomstrip
|
|
+-->
|
|
<div class="lastmodified">
|
|
<script type="text/javascript"><!--
|
|
document.write("Last Published: " + document.lastModified);
|
|
// --></script>
|
|
</div>
|
|
<div class="copyright">
|
|
Copyright ©
|
|
2001-2026 <a href="https://www.apache.org/">The Apache Software Foundation</a>
|
|
<br>
|
|
Apache POI, POI, Apache, the Apache logo, and the Apache
|
|
POI project logo are trademarks of The Apache Software Foundation.
|
|
</div>
|
|
<div id="feedback">
|
|
Send feedback about the website to:
|
|
<a id="feedbackto" href="mailto:dev@poi.apache.org?subject=Feedback%C2%A0devel/guidelines.html">dev@poi.apache.org</a>
|
|
</div>
|
|
<!--+
|
|
|end bottomstrip
|
|
+-->
|
|
</div>
|
|
</body>
|
|
</html>
|