Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Crafting lovely git narratives to enable software archaeology

Crafting lovely git narratives to enable software archaeology

mrgnrdrck

March 16, 2017
Tweet

More Decks by mrgnrdrck

Other Decks in Programming

Transcript

  1. "Archaeology is the study of human activity through the recovery

    and analysis of material culture" "Recovery and anlysis of material culture" => git history
  2. crafting lovely git narratives What makes a lovely git narrative?

    Each step in the narrative is well documented, unambiguous and easy to follow. - let each commit tell it's own story, as part of the bigger narrative - use good commit messages - make the diff read easy => group related work together, but not too much
  3. What is a good commit message? * http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html * https://robots.thoughtbot.com/5-useful-tips-for-a-better-commit-message

    * https://alistapart.com/article/the-art-of-the-commit Write more than one line for all non-trivial commits Give a brief description of motivation for the change Explain the solution, only in as much detail as a capable reader would need to understand the solution. Provide links to tickets in JIRA, github issues, etc.
  4. Intent vs. Implementation - Commit messages should describe requirements and

    intent, just like function names and test names - Changesets are implementation Without requirements and intent, it is very unlikely that the reader will have an accurate understanding of your intent, let alone find flaws in the implementation
  5. How do I create a lovely narrative? The same way

    that literary authors write good prose. Create a quick outline and keep editing until it reads well. For code stored in source control this means: - separate concerns into their own commits: - service tasks like fix whitespace, style compliance, etc - dependency management - adding missing tests - refactoring, probably each step in it's own commit - bug fixes - features - remove unused code - remove unused dependencies - Tell a story with your code (order is everything!) => rewrite history
  6. Learn to use rebase, stop using merge (git pull) git

    fetch upstream git rebase upstream/master https://www.atlassian.com/git/tutorials/merging-vs-rebasing Nobody wants to read several conversations mixed in with each other
  7. reword Allows you to change the commit message You can

    also use git commit --amend to change the commit message