diff options
Diffstat (limited to '.html/dev/commit-messages.html')
| -rw-r--r-- | .html/dev/commit-messages.html | 163 |
1 files changed, 163 insertions, 0 deletions
diff --git a/.html/dev/commit-messages.html b/.html/dev/commit-messages.html new file mode 100644 index 0000000..45a580e --- /dev/null +++ b/.html/dev/commit-messages.html @@ -0,0 +1,163 @@ +<!DOCTYPE html> +<html> +<head> + <title> + The Codex » + Writing Good Commit Messages + </title> + + <link + rel='stylesheet' + type='text/css' + href='http://fonts.googleapis.com/css?family=Buenard:400,700&subset=latin,latin-ext'> + <link + rel="stylesheet" + type="text/css" + href="../media/css/reset.css"> + <link + rel="stylesheet" + type="text/css" + href="../media/css/grimoire.css"> +</head> +<body> + +<div id="shell"> + + <ol id="breadcrumbs"> + + <li class="crumb-0 not-last"> + + <a href="../">index</a> + + </li> + + <li class="crumb-1 not-last"> + + <a href="./">dev</a> + + </li> + + <li class="crumb-2 last"> + + commit-messages + + </li> + + </ol> + + + + <div id="article"> + <h1 id="writing-good-commit-messages">Writing Good Commit Messages</h1> +<p>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.</p> +<p>Having said that, here are some things that will help your commit messages be +useful later:</p> +<ul> +<li> +<p>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. <em>It's okay for this to + be a “what” description</em> if the rest of the message is a “why” description.</p> +</li> +<li> +<p>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 <a href="comments">the + guidelines for good comments</a>, 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.</p> +</li> +<li> +<p>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.</p> +</li> +<li> +<p>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.</p> +</li> +<li> +<p>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.)</p> +<ul> +<li>This also applies to line-wrapping: either hard-wrap everywhere, or + hard-wrap nowhere.</li> +</ul> +</li> +</ul> +<h2 id="an-example">An Example</h2> +<pre><code>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. +</code></pre> + </div> + + + +<div id="comments"> +<div id="disqus_thread"></div> +<script type="text/javascript"> + /* * * CONFIGURATION VARIABLES: EDIT BEFORE PASTING INTO YOUR WEBPAGE * * */ + var disqus_shortname = 'grimoire'; // required: replace example with your forum shortname + + /* * * DON'T EDIT BELOW THIS LINE * * */ + (function() { + var dsq = document.createElement('script'); dsq.type = 'text/javascript'; dsq.async = true; + dsq.src = 'http://' + disqus_shortname + '.disqus.com/embed.js'; + (document.getElementsByTagName('head')[0] || document.getElementsByTagName('body')[0]).appendChild(dsq); + })(); +</script> +<noscript>Please enable JavaScript to view the <a href="http://disqus.com/?ref_noscript">comments powered by Disqus.</a></noscript> +<a href="http://disqus.com" class="dsq-brlink">comments powered by <span class="logo-disqus">Disqus</span></a> +</div> + + + + <div id="footer"> + <p> + + The Codex — + + Powered by <a href="http://markdoc.org/">Markdoc</a>. + +<a href="https://bitbucket.org/ojacobson/grimoire.ca/src/master/wiki/dev/commit-messages.md">See this page on Bitbucket</a> (<a href="https://bitbucket.org/ojacobson/grimoire.ca/history-node/master/wiki/dev/commit-messages.md">history</a>). + + </p> + </div> + +</div> +</body> +</html>
\ No newline at end of file |