Thoughts on commit messages

commit_message_rant.md

TL;DR: What's the interest in updating our release tool (probably as a 10% project) to let us not have to use 16+ characters before we start our summary? Are there any reasonable barriers?

So

I'm a big fan of the 50/72 commit message line length philosophy, and I think/hope most everyone else here is of the same opinion (but even if you're not, I still think you'll appreciate what follows). As such, I consider those first 50 characters precious and hate wasting them with something like "[CR] [12345678] " - that's a minimum of 16 characters!

Don't even get me started on when it's multiple authors and/or stories…

Thoughts:

My name is already in the commit history as the author (and committer), why included it again? Yes, I'm aware that omitting it leaves out the others who helped with the work, but there are solutions for that.

All those brackets aren't needed, especially if we just start with the story number(s). Wouldn't you prefer something like "12345678 - " to start your message? Yay, 5 more characters to work with!

Personally, I still think the story numbers are noise in the summary, and would rather have them on a later line in the commit message where I can grab it if I need it, but I'm not distracted by them.

How many of us know what stories 50276895 and 50263173 are about? There are commits from those stories that aren't even a day old.

There are tools that make writing commit messages as a pair easier, though I haven't spent any time actually evaluating them. There's also the old-fashioned way of writing your commit message manually and adding the stuff as needed (which most of us are probably doing anyway).

While moving information to subsequent lines will make it much tougher to do a git commit –m …, I'd argue that is for the best. I love my quick git commit messages, but as a result, I don't necessarily put the amount of time/effort into crafting an appropriate git commit message as I should. Being forced to open up the message in an editor would slow me down and hopefully prompt a more thorough commit message.

So, who's up for updating our qa_release_tasks gem and workflow so they support what I would term as cleaner and better commit messages?

I'd love to hear everyone else's thoughts on this.

At http://stackoverflow.com/questions/2706797/git-finding-what-branch-a-commit-came-from, the accepted answer shows a method for getting the branch name that a commit came from. Basically, it can be parsed from the output of

git reflog show --all | grep a871742

We could encode the branch names as XXX_XXX_DDDDDDDDD where you can add an arbitrary number of initials followed by the story number last. We could then eliminate any need for us to add data to commit messages. It would also eliminate a tendency towards trying tools for pair messages, which I'm not particularly interested in since I already took the time to learn Git.

One issue with this is that reflog entries over 90 days old get purged, but it shouldn't matter for purposes of compiling release data.

I'd be in favor of any solution that makes our commit messages shorter, provided we still have an easy way of:

1. Finding out who else worked on the commit (besides the comitter)
2. Linking the commit to the Pivotal story

Re: #2, I wish Pivotal had some way of showing all of the commits related to a story. JIRA does this, BTW, and it really comes in handy.

@turbodog99 - Wouldn't we lose the pair & story link data after a branch was merged/deleted?

No, the reflog stores where it came from for 90 days. Mine only shows stuff from the time I cloned forward, but I don't think that would be a problem on the box that's compiling this data.

I'm not sure if this would work, but if so, I think it would stay out of our way pretty well.

Here's an example of what's in it

3f768b2 refs/remotes/origin/jx-50337655-refactor-unit-group-presenter@{0}: pull: storing head
48d05b4 refs/remotes/origin/jx-50239247-refactor-featured-community-presenter@{0}: pull: storing head
18bd6e6 refs/remotes/origin/gi-50040557-refactor-saved-search-presenter@{0}: pull: forced-update
eef959f refs/remotes/origin/qa@{0}: pull: fast-forward
a9f9f10 refs/remotes/origin/MM_49998647@{0}: pull: storing head
1804d97 refs/heads/dev@{1}: rebase finished: refs/heads/dev onto 1804d972a9dd60be9c28b5067b105a1c3af00222
20746f9 f8f70c7 3842bd4 38bb7bb d3b08da 0b29e9a 7254648 9a3ecdd refs/remotes/origin/preserve_map_w_varnish_48414349@{0}: pull: storin
aa8a0d2 46986de e71b0a6 7402051 1f47fbe 8882d18 6aeacae cb9d4af 6346adb 06cdc95 1e2b4ca 2f73295 64f0569 d16f3dc refs/remotes/origin/j
8c2600c ede71db 13967ec refs/remotes/origin/gi-50208793-refactor-review-results-presenter@{0}: pull: storing head
bbac595 d06d4d4 refs/remotes/origin/py-50188297-refactor-nearby-presenter@{0}: pull: storing head
920cd5c 6320d74 3cac46a c7c2fd1 refs/heads/MAH_49532919@{0}: commit: [MAH][49532919] More thorough set of tests

Another, probably cleaner way:

Query all refs from Github. The commit ref with a given hash will have the branch name at the end of the URL.

For example:

 {
    "ref": "refs/heads/chr/remove_adv_search_btn_from_srl",
    "url": "https://api.github.com/repos/primedia/ag/git/refs/heads/chr/remove_adv_search_btn_from_srl",
    "object": {
      "sha": "c357047e38c8d6b3cb7970890c7b2e531df7ca51",
      "type": "commit",
      "url": "https://api.github.com/repos/primedia/ag/git/commits/c357047e38c8d6b3cb7970890c7b2e531df7ca51"
    }
  },

Okay, this won't save us characters, but Github includes Pivotal integration as an option. We'd need to include a pound sign with the story number in brackets. Details at https://www.pivotaltracker.com/help/api?version=v3#scm_post_commit

If Pivotal receives one of these events, it'll start the story automatically. It can also finish the story with certain words in the commit message.

I thought Pivotal was going away (eventually). Just saying we may need to adapt this as we evolve our ticketing system.