rules/source_repositories: ChangeLog changes.

1 files changed, 39 insertions, 18 deletions

diff --git a/rules/source_repositories.mdwn b/rules/source_repositories.mdwn
index ed09b8c6..2c54e7cf 100644
--- a/rules/source_repositories.mdwn
+++ b/rules/source_repositories.mdwn
@@ -27,9 +27,9 @@ tags can be applied recursively (`TOPIC-SUBTOPIC-SUBSUBTOPIC`).
 
 *private* vs. *public* does, of course, in this scenario not mean visibility,
 but instead authority: *private* branches are those that the user
-`SAVANNAH_LOGIN` has authority over, whereas public branches are open for
-every committer to install changes on.  The private branches are those that
-you would typically host on your own machine and publish through your own web
+`SAVANNAH_LOGIN` has authority over, whereas *public* branches are open for
+every committer to install changes on.  The private branches are those that you
+would typically host on your own machine and publish through your own web
 server, but we offer that you can instead do this from the centralized Savannah
 repository, as a number of people don't have an always-accessible web server
 running on their own machines.
@@ -86,26 +86,47 @@ written by ourselves, including new files, of course.
 GNU Mach code is largely based on external code.  Don't GNU-ify it, as this
 would make merging external patches unnecessarily difficult.
 
-## Behavior on branches
+## Commit messages
 
-Usually, branches are to be eventually merged back into their respective
-mainline branches.  To faciliate (and also to help other contributors) we'd
-like you to write a short summary log in a top-level (or wherever else
-appropriate) `ChangeLog.TOPIC` file.
+We no longer maintain parallel `ChangeLog` and commit messages.  When needed,
+the `ChangeLog` files can be created automatically from the commit messages.
 
-Examples:
+Commit messages have this mandatory format:
 
-  * GNU Mach
+    One-line summary.
+    Blank line.
+    ChangeLog-like list of changes, but without leading tabs.
+
+The header line of each former `ChangeLog` snippet (DATE NAME EMAIL) is no
+longer to be included in the commit message, and instead the author and
+committer of a change, together with the dates, will be maintained natively by
+Git.
+
+Example:
+
+    commit 3054666a46e0142cacef895c13edb4391435c722
+    Author:     Some One <someone@example.com>
+    AuthorDate: Thu Jun 11 15:59:55 2005 +0000
+    Commit:     Some One <someone@example.com>
+    CommitDate: Thu Jun 11 15:59:55 2005 +0000
+    
+        Frobnicate the foo.
+        
+        * frob.c (foo): Frob it.
+        * oldfoo.c [OLD] (oldfoo): Likewise.
+        [OLD_OLD_FOO] (oofoo): Permute every second word with itself, and
+        beginning with the tenth line, every third one also.  Pure
+        nonsense.
 
-      * `master-gdb_stubs`: `ChangeLog.gdb`
+Read about how to write [GNU-style `ChangeLog`
+messages](http://www.gnu.org/prep/standards/html_node/Change-Logs.html).
 
-This need not be a full-fledged [GNU-style `ChangeLog`
-file](http://www.gnu.org/prep/standards/html_node/Change-Logs.html).  E.g.,
-don't waste time writing `ChangeLog` entries for debugging stuff that will be
-removed again before merging back into mainline.  But please do write
-something.  Short notes.
+Don't waste time writing exhaustive `ChangeLog`-like commit messages for, e.g.,
+debugging stuff that will be removed again before merging your development
+branch into the mainline.  Sometimes the one-line summary might already
+suffice.  But please do write something.
 
-### Behavior on *private* branches
+## Behavior on *private* branches
 
 Even though you are said to be the owner of branches tagged with your
 `SAVANNAH_LOGIN`, it is generally nevertheless good to not do history-rewriting
@@ -115,4 +136,4 @@ their work on your private branches.
 We could establish a branch-tagging policy for branches that others should
 expect their history possibly to be rewritten.  This may be useful for branches
 that are only meant for aggregating the changes of (several) development
-branches, like `master-proposed_for_general_testing`.
+branches, like an imaginary `master-proposed_for_general_testing` branch.