Crafting lovely git narratives to enable software archaeology

Transcript

1. Crafting lovely git narratives to enable software archaeology Morgan Roderick - @mrgnrdrck
2. "Archaeology is the study of human activity through the recovery and analysis of material culture" "Recovery and anlysis of material culture" => git history
3. software archaeology Software Archaeology * peer review * finding root cause of bugs
5. log -S https://git-scm.com/docs/git-log#git-log--Sltstringgt Pickaxe Demo: find "lastName"
6. bisect https://git-scm.com/docs/git-bisect Binary search to quickly find first commit that introduced a problem
7. 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
8. Nightmare! 2 commits 292 files touched 25k lines added Don't be that person!
9. 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.
10. 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
11. Example of bad commit message
12. https://github.com/sozialhelden/accessibility-cloud/pull/21/ commits/677ad229ef4f434fa3ba4ba14ea2466187250c20? diff=unified Example of good commit message
13. 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
16. 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
17. let's rewrite history! https://git-scm.com/book/id/v2/Git-Tools-Rewriting-History Makes code reviews much easier Makes software archaeology much easier
18. git rebase -- interactive
19. reword Allows you to change the commit message You can also use git commit --amend to change the commit message
20. amend
21. merge squash fixup
22. split
23. GitHub uses date order
24. git log, git tower, etc. uses git database order
25. bonus: --ignore-date Write new dates on the new commits in your branch
26. Thank you! Morgan Roderick - @mrgnrdrck