Author: crossley
Date: Wed Aug 17 23:25:01 2005
New Revision: 233290
URL: http://svn.apache.org/viewcvs?rev=233290&view=rev
Log:
Expand the "Code management" section, clarify the commit-then-review
policy for decision-making, provide some tips for patch application.
Modified:
forrest/trunk/site-author/content/xdocs/guidelines.xml
Modified: forrest/trunk/site-author/content/xdocs/guidelines.xml
URL:
http://svn.apache.org/viewcvs/forrest/trunk/site-author/content/xdocs/guidelines.xml?rev=233290&r1=233289&r2=233290&view=diff
==============================================================================
--- forrest/trunk/site-author/content/xdocs/guidelines.xml (original)
+++ forrest/trunk/site-author/content/xdocs/guidelines.xml Wed Aug 17 23:25:01
2005
@@ -518,15 +518,58 @@
<section id="code">
<title>Code management</title>
+
+ <p>
+ The term "patch" has two meanings: Developers provide a set of changes
+ via our <link href="site:bugs">Issue Tracker</link> marked for inclusion,
+ which will be applied by a committer. Committers apply their own work
+ directly, but it is still essentially a patch.
+ </p>
+
<p>
We use the
<link
href="http://www.apache.org/foundation/glossary.html#CommitThenReview";>Commit-then-review</link>
- method. This basically means that committers conduct a very minor
- review of each patch, looking for major issues such as licensing
- issues and obvious things that would break the build of trunk.
- Otherwise they would add the patch as-is, then everyone will
- review the changes.
+ method for decision-making about code changes. Please refer to that
+ glossary definition. Note that it does not preclude the committer
+ from making changes to patches prior to their commit, nor mean that the
+ committer can be careless. Rather it is a policy for decision-making.
+ </p>
+
+ <p>
+ There is an important issue where both developers and committers need
+ to pay special attention: "licenses". We must not introduce licensing
+ conditions that go beyond the terms of the <link href="ext:asl">Apache
License</link>.
+ If such issues do creep in to our repository, then we must work as
+ quickly as possible to address it and definitely before the next release.
+ </p>
+
+ <p>
+ There are some other problem areas:
+ What should a committer do if the patch is sloppy, containing
inconsistent
+ whitespace and other code formatting, which mean that actual changes are
not
+ easily visible in the svn diff messages. What if there is poorly
constructed
+ (yet working) xml or java code? What if the new functionality is beyond
the
+ scope of the project? What if there is a better way to do the task? What
if
+ the patch will break the build, thereby preventing other developers from
+ working and causing an unstable trunk?
+ </p>
+
+ <p>
+ The committer has various options: ask the developer to resubmit the
patch;
+ change the patch to fix the problems prior to committing; discuss the
+ issues on the dev list; commit it and then draw attention to the
+ issues so that the rest of the community can review and fix it.
+ A combination of these options would appear to be the best approach.
+ Please aim to not break the build, or introduce license problems, or make
+ noisy changes that obscure the real differences.
+ </p>
+
+ <p>
+ Committers should not be afraid to add changes that still need attention.
+ This enables prompt patch application and eases the load on the
individual
+ committer. An interesting side-effect is that it encourages community
growth.
</p>
+
</section>
<!-- FIXME:
