Author: nick
Date: Mon Aug 4 14:30:15 2014
New Revision: 1615576
URL: http://svn.apache.org/r1615576
Log:
More on how to (and how not to!) contribute from the read-only Git repos, and
change the SVN default to be SSL for all (long supported)
Modified:
poi/site/src/documentation/content/xdocs/guidelines.xml
poi/site/src/documentation/content/xdocs/subversion.xml
Modified: poi/site/src/documentation/content/xdocs/guidelines.xml
URL:
http://svn.apache.org/viewvc/poi/site/src/documentation/content/xdocs/guidelines.xml?rev=1615576&r1=1615575&r2=1615576&view=diff
==============================================================================
--- poi/site/src/documentation/content/xdocs/guidelines.xml (original)
+++ poi/site/src/documentation/content/xdocs/guidelines.xml Mon Aug 4 14:30:15
2014
@@ -168,7 +168,8 @@
<section><title>Submitting Patches</title>
<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.
+ 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?).
@@ -240,10 +241,39 @@
echo " /tmp/poi-patch/new-files.tar.bz2"
</source>
</section>
+ <section><title>Approach 3 - the git way</title>
+ <p>
+ If you are working on a Git clone of Apache POI (see the
+ <link href="subversion.html">Version Control page</link> for
+ more on the read-only Git mirrors), it is possible to generate
+ a patch of your changes (including new binary files) using Git.
+ </p>
+ <p>
+ For new developers, we'd normally suggest using Subversion and
+ one of the methods above, as they tend to be simpler. For people
+ who are already proficient with Git, then generating a patch
+ from Git can be any easy way to contribute!
+ </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 noticable 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 the trap!
+ </p>
+ </section>
<section><title>checklist before submitting a patch</title>
<ul>
<li>added code complies with <link href="#CodeStyle">coding
standards</link></li>
- <li>added code compiles and runs on java 1.5</li>
+ <li>added code compiles and runs on java 1.6</li>
<li>new java files begin with the <link
href="http://www.apache.org/foundation/license-faq.html";>
apache software license</link> statement.</li>
<li>the code does not depend on gpl or lgpl code.</li>
@@ -251,7 +281,9 @@
<li>existing test cases succeed.</li>
<li>new test cases written and succeed.</li>
<li>documentation page extended as appropriate.</li>
+ <li>examples updated / added as appropriate.</li>
<li>diff files generated using svn diff</li>
+ <li>newly added files are included in the patch / alongside the
patch</li>
<li>the bugzilla 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(s).</li>
Modified: poi/site/src/documentation/content/xdocs/subversion.xml
URL:
http://svn.apache.org/viewvc/poi/site/src/documentation/content/xdocs/subversion.xml?rev=1615576&r1=1615575&r2=1615576&view=diff
==============================================================================
--- poi/site/src/documentation/content/xdocs/subversion.xml (original)
+++ poi/site/src/documentation/content/xdocs/subversion.xml Mon Aug 4 14:30:15
2014
@@ -23,7 +23,7 @@
<header>
<title>Apache POI - Source Code Repository</title>
<authors>
- <person id="NB" name="Nick Burch" email="[email protected]"/>
+ <person id="NB" name="Nick Burch" email="[email protected]"/>
</authors>
</header>
@@ -56,10 +56,9 @@
</p>
<p>
The root url of the ASF Subversion repository is
- <link
href="http://svn.apache.org/repos/asf/";>http://svn.apache.org/repos/asf/</link>
- for non-committers and
- <link
href="https://svn.apache.org/repos/asf/";>https://svn.apache.org/repos/asf/</link>
- for committers.
+ <link
href="https://svn.apache.org/repos/asf/";>https://svn.apache.org/repos/asf/</link>,
+ and the Apache POI source code lives within
+ <link
href="https://svn.apache.org/repos/asf/poi/";>https://svn.apache.org/repos/asf/poi/</link>
</p>
<p><strong>NOTE</strong>: When checking out a subproject using
@@ -69,9 +68,7 @@
</p>
<ul>
- <li>For read only access to the Apache POI svn, please use
- <link
href="http://svn.apache.org/repos/asf/poi/trunk/";>http://svn.apache.org/repos/asf/poi/trunk/</link></li>
- <li>For committers (write) access to the Apache POI svn, please use
+ <li>For read only access to the latest Apache POI code, please use
<link
href="https://svn.apache.org/repos/asf/poi/trunk/";>https://svn.apache.org/repos/asf/poi/trunk/</link></li>
<li>To browse the svn repository in your web browser, please us
<link href="http://svn.apache.org/viewcvs.cgi/poi/";>ViewSVN</link></li>
@@ -79,7 +76,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="guidelines.html">Guidelines</link> for more
+ <link href="guidelines.html">Contribution Guidelines</link> for more
information.</p>
</section>
<section><title>Git access to POI sources </title>
@@ -95,17 +92,18 @@
from <link href="http://git.apache.org/";>git.apache.org/</link> .
The Git Clone URL is: <link
href="git://git.apache.org/poi.git">git://git.apache.org/poi.git</link>
and Http Clone URL: <link
href="http://git.apache.org/poi.git";>http://git.apache.org/poi.git</link> .
- Please see the <link href="http://git.apache.org/";>Git at
- Apache</link> page for more details on the service.
+ Please see the <link href="http://git.apache.org/";>Git at
+ Apache</link> page for more details on the service.
</p>
<p>
- In addition to the <link
href="http://git.apache.org/";>git.apache.org/</link>
+ In addition to the <link
href="http://git.apache.org/";>git.apache.org</link>
repository, changes are also mirrored in near-realtime to GitHub.
The GitHub repository is available at
<link
href="https://github.com/apache/poi";>https://github.com/apache/poi</link> .
- Please note that the GitHub repository is read-only, and all
- contributions should continue to be sent via Bugzilla for tracking.
- (Git patches are fine though). Please see the
+ Please note that the GitHub repository is read-only, but pull requests
sent
+ to it will result in an email being sent to the mailing list. A
Git-formatted
+ patch added to Bugzilla is generally preferred though, as it can be
tracked
+ along with all the other contributions. Please see the
<link href="guidelines.html">contribution guidelines</link> for more
information on getting involved in the project.</p>
</section>
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
