Wrote out my theory on commit messages.

For context, also threw in my borrowed theory on comments.

2 files changed, 78 insertions, 0 deletions

diff --git a/wiki/dev/comments.md b/wiki/dev/comments.md
new file mode 100644
index 0000000..7dc1a68
--- /dev/null
+++ b/wiki/dev/comments.md
@@ -0,0 +1,8 @@
+# Comment Maturity Model
+
+> * Beginners comment nothing
+> * Apprentices comment the obvious
+> * Journeymen comment the reason for doing it
+> * Masters comment the reason for not doing it another way
+
+Richard C. Haven, via [cluefire.net](http://cluefire.net/)
diff --git a/wiki/dev/commit-messages.md b/wiki/dev/commit-messages.md
new file mode 100644
index 0000000..6661671
--- /dev/null
+++ b/wiki/dev/commit-messages.md
@@ -0,0 +1,70 @@
+# Writing Good Commit Messages
+
+Rule zero: "good" is defined by the standards of the project you're on. Have a
+look at what the existing messages look like, and try to emulate that first
+before doing anything else.
+
+Having said that, here are some things that will help your commit messages be
+useful later:
+
+* Treat the first line of the message as a one-sentence summary. Most SCM
+  systems have an "overview" command that shows shortened commit messages in
+  bulk, so making the very beginning of the message meaningful helps make
+  those modes more useful for finding specific commits. _It's okay for this to
+  be a "what" description_ if the rest of the message is a "why" description.
+
+* Fill out the rest of the message with prose outlining why you made the
+  change. The guidelines for a good "why" message are the same as [the
+  guidelines for good comments](comments), but commit messages can be
+  signifigantly longer. Don't bother reiterating the contents of the change in
+  detail; anyone who needs that can read the diff themselves.
+
+* If you use an issue tracker (and you should), include whatever issue-linking
+  notes it supports right at the start of the message, where it'll be visible
+  even in shortlogs. If your tracker has absurdly long issue-linking syntax,
+  or doesn't support issue links in commits at all, include a short issue
+  identifier at the front of the message and put the long part somewhere out
+  of the way, such as on a line of its own at the end of the message.
+
+* Pick a tense and a mood and stick with them. Reading one commit with a
+  present-tense imperative message ("Add support for PNGs") and another commit
+  with a past-tense narrative message ("Fixed bug in PNG support") is
+  distracting.
+
+* If you need rich commit messages (links, lists, and so on), pick one markup
+  language and stick with it. It'll be easier to write useful commit
+  formatters if you only have to deal with one syntax, rather than four.
+  (Personally, I use Markdown on projects I control.)
+
+    * This also applies to line-wrapping: either hard-wrap everywhere, or
+      hard-wrap nowhere.
+
+## An Example
+
+    commit 842e6c5f41f6387781fcc84b59fac194f52990c7
+    Author: Owen Jacobson <owen.jacobson@grimoire.ca>
+    Date:   Fri Feb 1 16:51:31 2013 -0500
+
+        DS-37: Add support for privileges, and create a default privileged user.
+
+        This change gives each user a (possibly empty) set of privileges. Privileges
+        are mediated by roles in the following ways:
+
+        * Each user is a member of zero or more roles.
+        * Each role implies membership in zero or more roles. If role A implies role
+          B, then a member of role A is also a transitive member of role B. This
+          relationship is transitive: if A implies B and B implies C, then A implies
+          C. This graph should not be cyclic, but it's harmless if it is.
+        * Each role grants zero or more privileges.
+
+        A user's privileges are the union of all privileges of all roles the user is a
+        member of, either directly or transitively.
+
+        Obviously, a role that implies no other roles and grants no priveleges is
+        meaningless to the authorization system. This may be useful for "advisory"
+        roles meant for human consumption.
+
+        This also introduces a user with the semi-magical name '*admin' (chosen
+        because asterisks cannot collide with player-chosen usernames), and the group
+        '*superuser' that is intended to hold all privileges. No privileges are yet
+        defined.