You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@poi.apache.org by ni...@apache.org on 2010/07/02 17:51:49 UTC
svn commit: r960038 - in /poi/trunk/src/documentation: ./ content/xdocs/
content/xdocs/getinvolved/ content/xdocs/hwpf/ content/xdocs/plan/
content/xdocs/spreadsheet/ content/xdocs/trans/ content/xdocs/trans/de/
content/xdocs/trans/es/
Author: nick
Date: Fri Jul 2 15:51:48 2010
New Revision: 960038
URL: http://svn.apache.org/viewvc?rev=960038&view=rev
Log:
Update the contributor guidelines (microsoft docs, smaller patches are better etc), and ensure we only have the one copy in /guidelines.html
Removed:
poi/trunk/src/documentation/content/xdocs/getinvolved/
Modified:
poi/trunk/src/documentation/content/xdocs/casestudies.xml
poi/trunk/src/documentation/content/xdocs/guidelines.xml
poi/trunk/src/documentation/content/xdocs/hwpf/index.xml
poi/trunk/src/documentation/content/xdocs/plan/index.xml
poi/trunk/src/documentation/content/xdocs/spreadsheet/hacking-hssf.xml
poi/trunk/src/documentation/content/xdocs/spreadsheet/how-to.xml
poi/trunk/src/documentation/content/xdocs/subversion.xml
poi/trunk/src/documentation/content/xdocs/trans/de/book.xml
poi/trunk/src/documentation/content/xdocs/trans/es/book.xml
poi/trunk/src/documentation/content/xdocs/trans/es/casestudies.xml
poi/trunk/src/documentation/content/xdocs/trans/guidelines.xml
poi/trunk/src/documentation/skinconf.xml
Modified: poi/trunk/src/documentation/content/xdocs/casestudies.xml
URL: http://svn.apache.org/viewvc/poi/trunk/src/documentation/content/xdocs/casestudies.xml?rev=960038&r1=960037&r2=960038&view=diff
==============================================================================
--- poi/trunk/src/documentation/content/xdocs/casestudies.xml (original)
+++ poi/trunk/src/documentation/content/xdocs/casestudies.xml Fri Jul 2 15:51:48 2010
@@ -46,7 +46,7 @@
<p>
We are actively seeking case studies for this page (after all it
just started). To submit a case study, either
- <link href="getinvolved/index.html">
+ <link href="guidelines.html">
submit a patch for this page</link> or email it to the
<link href="mailinglists.html">mailing list
</link> (with [PATCH] prefixed subject, please).
Modified: poi/trunk/src/documentation/content/xdocs/guidelines.xml
URL: http://svn.apache.org/viewvc/poi/trunk/src/documentation/content/xdocs/guidelines.xml?rev=960038&r1=960037&r2=960038&view=diff
==============================================================================
--- poi/trunk/src/documentation/content/xdocs/guidelines.xml (original)
+++ poi/trunk/src/documentation/content/xdocs/guidelines.xml Fri Jul 2 15:51:48 2010
@@ -23,10 +23,8 @@
<header>
<title>Apache POI - Contribution Guidelines</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"/>
+ <person name="Nick Burch" email="dev@poi.apache.org"/>
+ <person name="David Fisher" email="dev@poi.apache.org"/>
</authors>
</header>
@@ -93,24 +91,30 @@
<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
+ in POI is done strictly by using public information. Most of this Public
+ Information currently comes from the documentation that Microsoft
+ makes freely available (see above). The rest of the public information
includes sources from other open source projects, books that state the
purpose intended is for allowing implementation of the file format and
do not require any non-disclosure agreement and just hard work.
- We are intent on keeping it
- legal, by contributing patches you agree to do the same.
+ We are intent on keeping it legal, by contributing patches you agree to
+ do the same.
</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)
+ received such information from a person bound by such an agreement, you
+ cannot participate in this project. Sorry. Well, unless you can persuade
+ Microsoft to release you from the terms of the NDA on the grounds that
+ most of the information is now publically available. However, if you have
+ been party to a Microsoft NDA, you will need to get clearance from Microsoft
+ before contributing.
</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.
+ or similar, and have only made us of the public documentation.
</p>
</section>
</section>
@@ -130,12 +134,15 @@
<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>Check the <link href="http://issues.apache.org/bugzilla/buglist.cgi?product=POI">bug database</link> for simple problem reports, and write a patch to fix the problem</li>
+ <li>Review existing patches in the <link href="http://issues.apache.org/bugzilla/buglist.cgi?product=POI">bug database</link>, and report if they still apply, if they need unit tests atc.</li>
<li>Add in new features, see <link href="http://issues.apache.org/bugzilla/buglist.cgi?product=POI">Bug database</link> for suggestions.</li>
</ul>
<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
- <link href="http://wiki.apache.org/nutch/Becoming_A_Nutch_Developer">http://wiki.apache.org/nutch/Becoming_A_Nutch_Developer</link></p>
+ <link href="http://wiki.apache.org/nutch/Becoming_A_Nutch_Developer">http://wiki.apache.org/nutch/Becoming_A_Nutch_Developer</link>. The
+ <link href="http://community.apache.org/">Apache Community Development
+ Project</link> also provides guidance and mentoring for new contributors.</p>
</section>
<section><title>Submitting Patches</title>
<p>
@@ -148,6 +155,19 @@
path-preserving archive format, relative to your poi directory.
You'll attach both files in the next step.
</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 SVN in a timely fashion. Secondly, by sending in your
+ patches earlier rather than later, it's much easier to get feedback
+ on your coding and direction. If you've missed an easier way to do something,
+ or are duplicating some (probably hidden) existing code, or taking things
+ in an unusual direction, it's best to get the feedback sooner rather than
+ later! As such, when submitting patches to POI, as with other Apache
+ Software Foundation projects, do please try to submit early and often, rather
+ than "throwing a large patch over the wall" at the end.
+ </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.
@@ -179,8 +199,7 @@ svn diff > /tmp/poi-patch/diff.txt
# Capture any new files, as svn diff won't include them
# Preserve the path
-svn status | grep "^\?" | \
- awk '{printf "cp --parents %s /tmp/poi-patch/new-files/\n", $2 }' | sh -s
+svn status | grep "^\?" | awk '{printf "cp --parents %s /tmp/poi-patch/new-files/\n", $2 }' | sh -s
# tar up the new files
cd /tmp/poi-patch/new-files/
@@ -194,10 +213,43 @@ echo " /tmp/poi-patch/new-files.tar.bz
</source>
</section>
+ <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 <link href="mailinglists.html">dev mailing list</link>.</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
+ <link href="mailinglists.html">dev mailing list</link> 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
+ <link href="http://community.apache.org/">Apache Community Development
+ Project</link> website.</p>
+ </section>
+
</body>
- <footer>
- <legal>
+<footer>
+ <legal>
Copyright (c) @year@ The Apache Software Foundation. All rights reserved.
- </legal>
- </footer>
+ </legal>
+</footer>
</document>
Modified: poi/trunk/src/documentation/content/xdocs/hwpf/index.xml
URL: http://svn.apache.org/viewvc/poi/trunk/src/documentation/content/xdocs/hwpf/index.xml?rev=960038&r1=960037&r2=960038&view=diff
==============================================================================
--- poi/trunk/src/documentation/content/xdocs/hwpf/index.xml (original)
+++ poi/trunk/src/documentation/content/xdocs/hwpf/index.xml Fri Jul 2 15:51:48 2010
@@ -68,7 +68,7 @@
<p>If you come across a feature in XWPF that you need, and isn't currently
there, please do send in a patch to add the extra functionality! More details
on contributing patches are available on the <link
- href="../getinvolved/index.html">"Contribution to POI" page</link>.</p>
+ href="../guidelines.html">"Contribution to POI" page</link>.</p>
</section>
<section>
@@ -122,7 +122,7 @@
code easily. If you need any help getting started with JUnit test cases
for HWPF, please ask on the developers' mailing list! If you show that you
are prepared to stick at it you will most likely be given SVN commit
- access. See <link href="../getinvolved/index.html">"Contribution to POI" page</link>
+ access. See <link href="../guidelines.html">"Contribution to POI" page</link>
for more details and help getting started.</p>
<p>Of course we will help you as best as we can. However, presently there
Modified: poi/trunk/src/documentation/content/xdocs/plan/index.xml
URL: http://svn.apache.org/viewvc/poi/trunk/src/documentation/content/xdocs/plan/index.xml?rev=960038&r1=960037&r2=960038&view=diff
==============================================================================
--- poi/trunk/src/documentation/content/xdocs/plan/index.xml (original)
+++ poi/trunk/src/documentation/content/xdocs/plan/index.xml Fri Jul 2 15:51:48 2010
@@ -50,7 +50,7 @@
<p>Anyone can participate in this process. Please get involved in discussion
on <code>dev</code> and contribute patches for these summary planning
- documents via the normal <link href="../getinvolved/index.html">contribution</link>
+ documents via the normal <link href="../guidelines.html">contribution</link>
process.
</p>
Modified: poi/trunk/src/documentation/content/xdocs/spreadsheet/hacking-hssf.xml
URL: http://svn.apache.org/viewvc/poi/trunk/src/documentation/content/xdocs/spreadsheet/hacking-hssf.xml?rev=960038&r1=960037&r2=960038&view=diff
==============================================================================
--- poi/trunk/src/documentation/content/xdocs/spreadsheet/hacking-hssf.xml (original)
+++ poi/trunk/src/documentation/content/xdocs/spreadsheet/hacking-hssf.xml Fri Jul 2 15:51:48 2010
@@ -83,7 +83,7 @@
and work your way up.</p>
</section>
<section><title>What Else Should I Know?</title>
- <p>Make sure you <link href="../getinvolved/index.html">read the contributing section</link>
+ <p>Make sure you <link href="../guidelines.html">read the contributing section</link>
as it contains more generation information about contributing to POI in general.</p>
</section>
</body>
Modified: poi/trunk/src/documentation/content/xdocs/spreadsheet/how-to.xml
URL: http://svn.apache.org/viewvc/poi/trunk/src/documentation/content/xdocs/spreadsheet/how-to.xml?rev=960038&r1=960037&r2=960038&view=diff
==============================================================================
--- poi/trunk/src/documentation/content/xdocs/spreadsheet/how-to.xml (original)
+++ poi/trunk/src/documentation/content/xdocs/spreadsheet/how-to.xml Fri Jul 2 15:51:48 2010
@@ -736,7 +736,7 @@ yet. When it does something, we'll docum
<li>Performance: POI currently uses a lot of memory for large sheets.</li>
<li>Charts: This is a hard problem, with very little documentation.</li>
</ul>
-<p><link href="../getinvolved/index.html"> So jump in! </link> </p>
+<p><link href="../guidelines.html"> So jump in! </link> </p>
</section>
Modified: poi/trunk/src/documentation/content/xdocs/subversion.xml
URL: http://svn.apache.org/viewvc/poi/trunk/src/documentation/content/xdocs/subversion.xml?rev=960038&r1=960037&r2=960038&view=diff
==============================================================================
--- poi/trunk/src/documentation/content/xdocs/subversion.xml (original)
+++ poi/trunk/src/documentation/content/xdocs/subversion.xml Fri Jul 2 15:51:48 2010
@@ -70,7 +70,7 @@
<p>If you are not a <em>Committer</em>, but you want to submit patches
or even request commit privileges, please see our
- <link href="getinvolved/index.html">Guidelines</link> for more
+ <link href="guidelines.html">Guidelines</link> for more
information.</p>
</section>
<section><title>Git access to POI sources </title>
Modified: poi/trunk/src/documentation/content/xdocs/trans/de/book.xml
URL: http://svn.apache.org/viewvc/poi/trunk/src/documentation/content/xdocs/trans/de/book.xml?rev=960038&r1=960037&r2=960038&view=diff
==============================================================================
--- poi/trunk/src/documentation/content/xdocs/trans/de/book.xml (original)
+++ poi/trunk/src/documentation/content/xdocs/trans/de/book.xml Fri Jul 2 15:51:48 2010
@@ -42,7 +42,7 @@
<menu-item label="Neuigkeiten" href="../../news.html"/>
<menu-item label="Änderungen" href="../../changes.html"/>
<menu-item label="Aufgaben" href="../../todo.html"/>
- <menu-item label="Mitmachen" href="../../getinvolved/index.html"/>
+ <menu-item label="Mitmachen" href="../../guidelines.html"/>
<menu-item label="Unsere Vision" href="../../plan/POI20Vision.html"/>
<menu-item label="Vergangenheit und Zukunft" href="../../historyandfuture.html"/>
<menu-item label="Wer wir sind" href="../../who.html"/>
Modified: poi/trunk/src/documentation/content/xdocs/trans/es/book.xml
URL: http://svn.apache.org/viewvc/poi/trunk/src/documentation/content/xdocs/trans/es/book.xml?rev=960038&r1=960037&r2=960038&view=diff
==============================================================================
--- poi/trunk/src/documentation/content/xdocs/trans/es/book.xml (original)
+++ poi/trunk/src/documentation/content/xdocs/trans/es/book.xml Fri Jul 2 15:51:48 2010
@@ -47,7 +47,7 @@
<menu-item label="Espejos [EN]" href="../../mirrors.html"/>
<menu-item label="Cambios [EN]" href="../../changes.html"/>
<menu-item label="Tareas" href="todo.html"/>
- <menu-item label="Contribuya [EN]" href="../../getinvolved/index.html"/>
+ <menu-item label="Contribuya [EN]" href="../../guidelines.html"/>
<menu-item label="Listas de Correo" href="http://jakarta.apache.org/site/mail2.html#poi"/>
<menu-item label="Visión [EN]" href="../../plan/POI20Vision.html"/>
<menu-item label="Historia y Futuro" href="historyandfuture.html"/>
Modified: poi/trunk/src/documentation/content/xdocs/trans/es/casestudies.xml
URL: http://svn.apache.org/viewvc/poi/trunk/src/documentation/content/xdocs/trans/es/casestudies.xml?rev=960038&r1=960037&r2=960038&view=diff
==============================================================================
--- poi/trunk/src/documentation/content/xdocs/trans/es/casestudies.xml (original)
+++ poi/trunk/src/documentation/content/xdocs/trans/es/casestudies.xml Fri Jul 2 15:51:48 2010
@@ -48,7 +48,7 @@
acaba de comenzarse). Andrew C. Oliver (acoliver at apache dot org) ha
accedido a entregar unas cuantas Camisetas con el logotipo de POI para
los primeros y mejores envíos. Para enviar un estudio de un caso, puedes
- <link href="http://jakarta.apache.org/poi/getinvolved/index.html">
+ <link href="http://jakarta.apache.org/poi/guidelines.html">
enviar un parche para esta página</link> o enviarlo por correo electrónico
a la <link href="http://jakarta.apache.org/site/mail2.html#poi">lista de correo
</link> (con [PATCH] como prefijo en el asunto, por favor).
Modified: poi/trunk/src/documentation/content/xdocs/trans/guidelines.xml
URL: http://svn.apache.org/viewvc/poi/trunk/src/documentation/content/xdocs/trans/guidelines.xml?rev=960038&r1=960037&r2=960038&view=diff
==============================================================================
--- poi/trunk/src/documentation/content/xdocs/trans/guidelines.xml (original)
+++ poi/trunk/src/documentation/content/xdocs/trans/guidelines.xml Fri Jul 2 15:51:48 2010
@@ -80,7 +80,7 @@
</p>
<p>
Submitting translations is simple, you follow the same
- <link href="/getinvolved/index.html">instructions</link> as you would for submitting a code patch.
+ <link href="/guidelines.html">instructions</link> as you would for submitting a code patch.
Remeber to always generate patchs in diff -u format preserving the context relative to the jakarta-poi directory. Also remember
to submit any new files in a directory preserving archive format. Never post these to the list, always use
<link href="http://issues.apache.org/bugzilla/buglist.cgi?product=POI&short_desc=%5BPATCH%5D&short_desc_type=allwordssubstr">Bugzilla</link>
Modified: poi/trunk/src/documentation/skinconf.xml
URL: http://svn.apache.org/viewvc/poi/trunk/src/documentation/skinconf.xml?rev=960038&r1=960037&r2=960038&view=diff
==============================================================================
--- poi/trunk/src/documentation/skinconf.xml (original)
+++ poi/trunk/src/documentation/skinconf.xml Fri Jul 2 15:51:48 2010
@@ -114,7 +114,7 @@ be used to configure the chosen Forrest
<host-logo></host-logo>
<!-- The following are used to construct a copyright statement -->
- <year>2002-2009</year>
+ <year>2002-2010</year>
<vendor>The Apache Software Foundation</vendor>
<!-- Some skins use this to form a 'breadcrumb trail' of links. If you don't
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@poi.apache.org
For additional commands, e-mail: commits-help@poi.apache.org