Migrate to Hugo.

This is a big and somewhat complicated decision, but the crux of it is this:

The _mkdocs_ tool embeds a ton of "I am writing a manual" assumptions about document structure.

These assumptions include that there is a single, sitewide TOC, that a top nav bar is broadly an appropriate way to skip around in the document, and numerous others. They serve that use case well, but that's not really what this site _is_, or how I intend it to be approached. I'm trying for something more blog-esque (and deliberately a bit haphazard).

Hugo is an experiment. This commit migrates most pages to it, but it does drop a few; this is a convenient excuse to forget items I'd prefer not to continue publishing.

1 files changed, 20 insertions, 0 deletions

diff --git a/content/code/commit-messages.md b/content/code/commit-messages.md
new file mode 100644
index 0000000..94b83f8
--- /dev/null
+++ b/content/code/commit-messages.md
@@ -0,0 +1,20 @@
+---
+title: Writing Good Commit Messages
+date: 2013-02-12T09:42:01-0500
+---
+
+A style guide.
+
+<!--more-->
+
+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 principles I've found helpful and broadly applicable.
+
+* 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. Don't reiterate the contents of the change in great detail if you can avoid it: anyone who needs that can read the diff themselves, or reach out to ask for help understanding the change. A good rationale sets context for the problem being solved and addresses the ways the proposed change alters that context.
+
+* 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 summarized commit logs. 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.
+
+* 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 when I can, or a reduced subset of Markdown, as it's something most developers I interact with will be at least passing familiar with.