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: