[gnome-utils] [docs] Add documentation on commit practises

[Emmanuele Bassi <ebassi src gnome org>]

commit 40697230f15ac1e6f6e0944934473d06203ff546
Author: Emmanuele Bassi <ebassi gnome org>
Date:   Fri Apr 17 17:56:49 2009 +0100

    [docs] Add documentation on commit practises
    
    Up until now we kinda left the commit practises up to the people
    actually committing.
    
    Since now we're starting to use commit messages and since now we
    use a tool that can potentially disrupt the history of the project,
    we need to be more careful.
---
 README.commits |   73 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 73 insertions(+), 0 deletions(-)

diff --git a/README.commits b/README.commits
new file mode 100644
index 0000000..97fb4fd
--- /dev/null
+++ b/README.commits
@@ -0,0 +1,73 @@
+The GNOME Utilities project follows some rules on how and what to
+commit to the public repository:
+
+0) Ask first. If your changes are major, or could possibly break existing
+   code, you should always ask. If your change is minor and you've
+   been working on gnome-utils for a while it probably isn't necessary
+   to ask. But when in doubt, ask. Even if your change is correct,
+   somebody may know a better way to do things.
+
+1) Ask _first_.
+
+2) With git, we no longer maintain a ChangeLog file, but you are expected
+   to produce a meaningful commit message. Changes without a sufficient
+   commit message will be reverted. See below for the expected format
+   of commit messages.
+
+Notes:
+
+* When developing larger features or complicated bug fixes, it is
+  advisable to work in a branch in your own cloned gnome-utils repository.
+  You may even consider making your repository publically available
+  so that others can easily test and review your changes.
+
+* The expected format for git commit messages is as follows:
+
+=== begin example commit ===
+Short explanation of the commit
+
+Longer explanation explaining exactly what's changed, whether any
+external or private interfaces changed, what bugs were fixed (with bug
+tracker reference if applicable) and so forth. Be concise but not too brief.
+=== end example commit ===
+
+  - Always add a brief description of the commit to the _first_ line of
+    the commit and terminate by two newlines (it will work without the
+    second newline, but that is not nice for the interfaces).
+
+  - First line (the brief description) must only be one sentence and
+    should start with a capital letter unless it starts with a lowercase
+    symbol or identifier. Don't use a trailing period either. Don't exceed
+    72 characters.
+
+  - The brief description might optionally have a "tag", enclosed in
+    square brackets, detailing what part of the repository the commit
+    affected, e.g.:
+
+      [dictionary] Added history support
+      [screenshot] Set shadow as default effect
+
+    The tag counts as part of overall character count, so try using
+    a short word.
+
+    If the change affects more than one sub-module, do not use a tag.
+
+    If the change affects the build environment, always use the "[build]"
+    tag.
+
+  - The main description (the body) is normal prose and should use normal
+    punctuation and capital letters where appropriate. Normally, for patches
+    sent to a mailing list it's copied from there.
+
+  - When committing code on behalf of others use the --author option, e.g.
+    git commit -a --author "Joe Coder <joe coder org>" and --signoff.
+
+  - We favour micro-commits: small, atomic changes that do not break
+    bisection and that are easy to cherry pick. If your commit changes
+    more than one file or more than one sub-module and it's not a build
+    fix then you're probably doing it wrong. Break up the changes by
+    using the -p option to the add command.
+
+  - Do NOT EVER, under ANY circumstances rebase a public branch. Do NOT
+    EVER remove a tag. Your commit rights will be revoked if you decide
+    to rewrite the history.