[[[
Rework branch and log message documentation. Tidy HTML.
* community-guide/conventions.part.html
(log-messages): Rework relocated branch log message documentation
moved from community-guide/general.part.html#lightweight-branches.
Remove mention of 'CIA' and substitute with ASFBot and update
link. Adjust paragraph containing link to 'partial-commit-access'
to columns limit.
* community-guide/general.part.html
(branch-creation-and-management): Add link to log message section.
(lightweight-branches): Relocate documentation pertaining to log
messages to community-guide/conventions.part.html#log-messages.
]]]
Index: community-guide/conventions.part.html
===================================================================
--- community-guide/conventions.part.html (revision 1479254)
+++ community-guide/conventions.part.html (working copy)
@@ -849,18 +849,33 @@ surprising frequency, too: for example, it might b
original commit and now the change is being ported to a maintenance
branch.</p>
-<p>The log message is the introduction to the change. Start it off
-with one line indicating the general nature of the change, and follow
-that with a descriptive paragraph if necessary. This not only helps
-put developers in the right frame of mind for reading the rest of the
-log message, but also plays well with the "CIA" bot that echoes the
-first line of each commit to realtime forums like IRC. (For details,
-see <a href="http://cia.vc/";>http://cia.vc/</a>.) However, if the
-commit is just one simple change to one file, then you can dispense
-with the general description and simply go straight to the detailed
-description, in the standard filename-then-symbol format shown
-below.</p>
+<p>The log message is the introduction to the change.</p>
+<ul>
+<li><p>If you are working on a branch, prefix your log message with:</p>
+<pre>
+ On the 'name-of-branch' branch: (Start of your log message)
+</pre>
+</li>
+<li>
+<p>Start your log message with one line indicating the general nature
+of the change, and follow that with a descriptive paragraph if
+necessary. </p>
+</li>
+</ul>
+
+<p> This not only helps put developers in the right frame of mind for
+reading the rest of the log message, but also plays well with the
+"ASFBot" bot that echoes the first line of each commit to realtime
+forums like IRC. (For details, see
+<a href="http://wilderness.apache.org/";>http://wilderness.apache.org/</a>
+)</p>
+
+<p> If the commit is just one simple change to one file, then you can
+dispense with the general description and simply go straight to the
+detailed description, in the standard filename-then-symbol format
+shown below.</p>
+
<p>Throughout the log message, use full sentences, not sentence
fragments. Fragments are more often ambiguous, and it takes only a
few more seconds to write out what you mean. Certain fragments like
@@ -973,9 +988,9 @@ of changes that accomplishes a single goal, and ea
start with a sentence or two summarizing the change. Truly
independent changes should be made in separate commits, of course.</p>
-<p>See <a href="<!--#echo var="GUIDE_CONVENTIONS_PAGE" -->#crediting">Crediting</a> for how to give credit to
-someone else if you are committing their patch, or committing a change
-they suggested.</p>
+<p>See <a href="<!--#echo var="GUIDE_CONVENTIONS_PAGE" -->#crediting">
+Crediting</a> for how to give credit to someone else if you are
+committing their patch, or committing a change they suggested.</p>
<p>One should never need the log entries to understand the current
code. If you find yourself writing a significant explanation in the
@@ -1032,6 +1047,21 @@ Malagasy translation." Please write your log mess
everybody involved in the project can understand the changes you
made.</p>
+<p>If you're using a branch to "checkpoint" your code, and don't feel
+it's ready for review, please put some sort of notice at the top of
+the log message, after the 'On the 'xxx' branch notice', such as:</p>
+
+<pre>
+ *** checkpoint commit -- please don't waste your time reviewing it ***
+</pre>
+
+<p>And if a later commit on that branch <em>should</em> be reviewed,
+then please supply, in the log message, the appropriate 'svn diff'
+command, since the diff would likely involve two non-adjacent commits
+on that branch, and reviewers shouldn't have to spend time figuring
+out which ones they are.</p>
+
+
</div> <!-- log-messages -->
Index: community-guide/general.part.html
===================================================================
--- community-guide/general.part.html (revision 1479254)
+++ community-guide/general.part.html (working copy)
@@ -432,6 +432,11 @@ in this way, so making good use of that feature (b
1.5 or newer clients, and by performing all merges to and from the
roots of branches) is highly encouraged.</p>
+<p>For our policy on log messages for your branch, please note the
+section on
+<a href="<!--#echo var="GUIDE_CONVENTIONS_PAGE" -->#log-messages">
+writing log messages.</a></p>
+
</div> <!-- branch-creation-and-management -->
<div class="h3" id="lightweight-branches">
@@ -450,27 +455,14 @@ applies to committers of other <a href="http://www
projects, but please talk to us (on dev@)—introduce yourself
and the problem you plan to work on.</p>
-<p>If you're just using the branch to "checkpoint" your code, and
-don't feel it's ready for review, please put some sort of notice at
-the top of the log message, such as:</p>
-
-<pre>
- *** checkpoint commit -- please don't waste your time reviewing it ***
-</pre>
-
-<p>And if a later commit on that branch <em>should</em> be reviewed,
-then please supply, in the log message, the appropriate 'svn diff'
-command, since the diff would likely involve two non-adjacent commits
-on that branch, and reviewers shouldn't have to spend time figuring
-out which ones they are.</p>
-
<p>When you're done with the branch — when you've
either merged it to trunk or given up on it — please
remember to remove it.</p>
-<p>See also the <a href="<!--#echo var="GUIDE_ROLES_PAGE" -->#partial-commit-access" >section on partial
-commit access</a> for our policy on offering commit access to
-experimental branches.</p>
+<p>See also the
+<a href="<!--#echo var="GUIDE_ROLES_PAGE" -->#partial-commit-access" >
+section on partial commit access</a> for our policy on offering commit
+access to experimental branches.</p>
</div> <!-- lightweight-branches -->
