Documentation Tradeoffs and Why Commit Messages are Worth Spending Time On

We've all thought "what is this thing supposed to do?" or "why was this done that way" moment when looking through codebases and unless there's documentation or you can find the author, the answer is often hard to find. There are many options to document code from comments to internal wikis, so I'll discuss a heuristic for evaluating the options based on the accessibility (how far away is the answer?) and accuracy (how likely is it that what I'm reading is out of date?) to build a case that the git commit message is likely where you should spend your energy documenting. I'll share my workflow and how to leverage tools tools like git-blame to get the most out of your git history.

Transcript

1. Documentation Tradeoffs and Why Commit Messages are Worth Spending Time On 
 
 Greggory Rothmeier @greggroth Stitch Fix
3. Accurate Accessible # outputs "Hello"
6. Context Building
7. Git Log
8. Git Blame VS Code | GitLens
9. Git Blame Atom | Better Git Blame
10. What makes a commit message useful? Title Start with a capitalized present tense verb, less than 50 characters, descriptive Description • Why did I do it this way? • What other ways did I consider? • What would I want to know if I were reading this in a few months? years? Issue Tracker Connects the code with where more information can be found (specs, mocks, etc.)
11. # Please enter the commit message for your changes. Lines starting # with '#' will be ignored, and an empty message aborts the commit. # add posts
12. # Please enter the commit message for your changes. Lines starting # with '#' will be ignored, and an empty message aborts the commit. # Add Post model and table
13. # Please enter the commit message for your changes. Lines starting # with '#' will be ignored, and an empty message aborts the commit. # Add Post model and table Add basic Post model including a view which allows a user to create and edit a post’s title and body. For now, there is no association with a user, but that will be added in #12346.
14. # Please enter the commit message for your changes. Lines starting # with '#' will be ignored, and an empty message aborts the commit. # Add Post model and table Add basic Post model including a view which allows a user to create and edit a post’s title and body. For now, there is no association with a user, but that will be added in #12346. [#12345]
15. How?
16. Rebasing HEAD 70117fd 32090b0 $ git status master On branch master nothing to commit, working tree clean
17. Rebasing add_posts HEAD 70117fd 32090b0 $ git checkout -b add_posts master
18. 89f5697 Rebasing add_posts HEAD 70117fd 32090b0 $ git checkout -b add_posts $ git add --all && git commit -m "WIP" master
19. 89f5697 add_posts Rebasing 70117fd 32090b0 $ git checkout -b add_posts $ git checkout master HEAD $ git add --all && git commit -m "WIP" master
20. Rebasing 70117fd 32090b0 $ git checkout -b add_posts $ git checkout master $ git pull a1203c3 $ git add --all && git commit -m "WIP" 89f5697 add_posts master HEAD
21. 89f5697 add_posts HEAD 70117fd 32090b0 $ git checkout -b add_posts $ git checkout master $ git pull a1203c3 $ git checkout add_posts $ git add --all && git commit -m "WIP" Rebasing master add_posts
22. 89f5697 HEAD add_posts 70117fd 32090b0 $ git checkout -b add_posts $ git checkout master $ git pull a1203c3 $ git checkout add_posts $ git rebase master $ git add --all && git commit -m "WIP" Rebasing master
23. HEAD add_posts 70117fd 32090b0 $ git checkout -b add_posts $ git checkout master $ git pull a1203c3 $ git checkout add_posts $ git rebase master $ git add --all && git commit -m "WIP" Rebasing master
24. HEAD add_posts caad9e1 HEAD add_posts 70117fd 32090b0 $ git checkout -b add_posts $ git checkout master $ git pull a1203c3 $ git checkout add_posts $ git rebase master master $ git add --all && git commit -m "WIP" Rebasing
25. Interactive Rebase HEAD 70117fd 32090b0 $ git checkout -b add_posts $ git add --all && git commit -m "WIP" add_posts 32090b0 $ git checkout master $ git pull a1203c3 $ git checkout add_posts 5ca6efe 82b114f extra work . . . $ git rebase --interactive master master WIP
26. pick 32090b0 Generate and run migration pick 5ca6efe WIP views pick 82b114f Add class file and finish views
 # Rebase 32090b0..82b114f onto a1203c3(3 commands) # # Commands: # p, pick <commit> = use commit # r, reword <commit> = use commit, but edit the commit message # e, edit <commit> = use commit, but stop for amending # s, squash <commit> = use commit, but meld into previous commit # f, fixup <commit> = like "squash", but discard this commit's log message # x, exec <command> = run command (the rest of the line) using shell # d, drop <commit> = remove commit # l, label <label> = label current HEAD with a name # t, reset <label> = reset HEAD to a label # m, merge [-C <commit> | -c <commit>] <label> [# <oneline>] # . create a merge commit using the original merge commit's # . message (or the oneline, if no original merge commit was # . specified). Use -c <commit> to reword the commit message. # # These lines can be re-ordered; they are executed from top to bottom. # # If you remove a line here THAT COMMIT WILL BE LOST. # # However, if you remove everything, the rebase will be aborted. # # # Note that empty commits are commented out
27. pick 32090b0 Generate and run migration pick 5ca6efe WIP views pick 82b114f Add class file and finish views
 # Rebase 32090b0..82b114f onto a1203c3(3 commands) # # Commands: # p, pick <commit> = use commit # r, reword <commit> = use commit, but edit the commit message # e, edit <commit> = use commit, but stop for amending # s, squash <commit> = use commit, but meld into previous commit # f, fixup <commit> = like "squash", but discard this commit's log message # x, exec <command> = run command (the rest of the line) using shell # d, drop <commit> = remove commit # l, label <label> = label current HEAD with a name # t, reset <label> = reset HEAD to a label # m, merge [-C <commit> | -c <commit>] <label> [# <oneline>] # . create a merge commit using the original merge commit's # . message (or the oneline, if no original merge commit was # . specified). Use -c <commit> to reword the commit message. # # These lines can be re-ordered; they are executed from top to bottom. # # If you remove a line here THAT COMMIT WILL BE LOST. # # However, if you remove everything, the rebase will be aborted. # # # Note that empty commits are commented out
28. pick 32090b0 Generate and run migration pick 5ca6efe WIP views pick 82b114f Add class file and finish views
 # Rebase 32090b0..82b114f onto a1203c3(3 commands) # # Commands: # p, pick <commit> = use commit # r, reword <commit> = use commit, but edit the commit message # e, edit <commit> = use commit, but stop for amending # s, squash <commit> = use commit, but meld into previous commit # f, fixup <commit> = like "squash", but discard this commit's log message # x, exec <command> = run command (the rest of the line) using shell # d, drop <commit> = remove commit # l, label <label> = label current HEAD with a name # t, reset <label> = reset HEAD to a label # m, merge [-C <commit> | -c <commit>] <label> [# <oneline>] # . create a merge commit using the original merge commit's # . message (or the oneline, if no original merge commit was # . specified). Use -c <commit> to reword the commit message. # # These lines can be re-ordered; they are executed from top to bottom. # # If you remove a line here THAT COMMIT WILL BE LOST. # # However, if you remove everything, the rebase will be aborted. # # # Note that empty commits are commented out
29. pick 32090b0 Generate and run migration pick 5ca6efe WIP views pick 82b114f Add class file and finish views # Rebase 32090b0..82b114f onto a1203c3(3 commands) # # Commands: # p, pick <commit> = use commit # r, reword <commit> = use commit, but edit the commit message # e, edit <commit> = use commit, but stop for amending # s, squash <commit> = use commit, but meld into previous commit # f, fixup <commit> = like "squash", but discard this commit's log message # x, exec <command> = run command (the rest of the line) using shell # d, drop <commit> = remove commit # l, label <label> = label current HEAD with a name # t, reset <label> = reset HEAD to a label # m, merge [-C <commit> | -c <commit>] <label> [# <oneline>] # . create a merge commit using the original merge commit's # . message (or the oneline, if no original merge commit was # . specified). Use -c <commit> to reword the commit message. # # These lines can be re-ordered; they are executed from top to bottom. # # If you remove a line here THAT COMMIT WILL BE LOST. # # However, if you remove everything, the rebase will be aborted. # # # Note that empty commits are commented out
30. pick 32090b0 Generate and run migration squash 5ca6efe WIP views squash 82b114f Add class file and finish views
 # Rebase 32090b0..82b114f onto a1203c3(3 commands) # # Commands: # p, pick <commit> = use commit # r, reword <commit> = use commit, but edit the commit message # e, edit <commit> = use commit, but stop for amending # s, squash <commit> = use commit, but meld into previous commit # f, fixup <commit> = like "squash", but discard this commit's log message # x, exec <command> = run command (the rest of the line) using shell # d, drop <commit> = remove commit # l, label <label> = label current HEAD with a name # t, reset <label> = reset HEAD to a label # m, merge [-C <commit> | -c <commit>] <label> [# <oneline>] # . create a merge commit using the original merge commit's # . message (or the oneline, if no original merge commit was # . specified). Use -c <commit> to reword the commit message. # # These lines can be re-ordered; they are executed from top to bottom. # # If you remove a line here THAT COMMIT WILL BE LOST. # # However, if you remove everything, the rebase will be aborted. # # # Note that empty commits are commented out
31. (32090b0) (5ca6efe) 5ca6efe (82b114f) 32090b0 Interactive Rebase 70117fd 32090b0 $ git checkout -b add_posts $ git add —all && git commit –m ”WIP” add_posts $ git checkout master $ git pull a1203c3 $ git checkout add_posts 82b114f extra work . . . $ git rebase --interactive master HEAD master
32. # This is a combination of 3 commits. # This is the 1st commit message: Generate and run migration # This is the commit message #2: WIP views # This is the commit message #3: Add class file and finish views # Please enter the commit message for your changes. Lines starting # with '#' will be ignored, and an empty message aborts the commit. #
33. Add Post model and table Add basic Post model including a view which allows a user to create and edit a post’s title and body. For now, there is no association with a user, but that will be added in #12346. [#12345]
34. Interactive Rebase 70117fd 32090b0 $ git checkout -b add_posts $ git add --all && git commit -m "WIP" $ git checkout master $ git pull a1203c3 $ git checkout add_posts (5ca6efe) (82b114f) extra work . . . $ git rebase --interactive master (32090b0) (32090b0 + 5ca6efe + 82b114f) add_posts HEAD master
35. Interactive Rebase 70117fd 32090b0 $ git checkout -b add_posts $ git add --all && git commit -m "WIP" $ git checkout master $ git pull a1203c3 $ git checkout add_posts extra work . . . $ git rebase --interactive master (32090b0 + 5ca6efe + 82b114f) add_posts HEAD master
36. add_posts HEAD b9e0e8 Interactive Rebase 70117fd 32090b0 $ git checkout -b add_posts $ git add --all && git commit -m "WIP" $ git checkout master $ git pull a1203c3 $ git checkout add_posts extra work . . . $ git rebase --interactive master (32090b0 + 5ca6efe + 82b114f) master
38. -m "Fix test" Amending a commit .............................................F Fix Things... $ git add --all && git commit --amend $ git log --oneline 89f5697 (HEAD -> add_posts) Fix tests b9e0e8e Add Post model and table a1203c3 (master) Initial commit
39. Add Post model and table Add basic Post model including a view which allows a user to create and edit a post’s title and body. For now, there is no association with a user, but that will be added in #12346. [#12345] # Please enter the commit message for your changes. Lines starting # with '#' will be ignored, and an empty message aborts the commit. #
40. Amending a commit $ git add --all && git commit --amend [add_posts 2b2da40] Add Post model and table Date: Tue Nov 6 14:13:57 2018 -0800 22 files changed, 395 insertions(+) create mode 100644 app/assets/javascripts/posts.coffee create mode 100644 app/assets/stylesheets/posts.scss create mode 100644 app/assets/stylesheets/scaffolds.scss create mode 100644 app/controllers/posts_controller.rb create mode 100644 app/helpers/posts_helper.rb create mode 100644 app/models/post.rb create mode 100644 app/views/posts/_form.html.erb ...
41. Amending a commit .............................................. $ git log --oneline 0ea7fed (HEAD -> add_posts) Add Post model and table a1203c3 (master) Initial commit
42. $ git push To github.com:greggroth/blog.git ! [rejected] add_posts -> add_posts (non-fast-forward) error: failed to push some refs to 'git@github.com:greggroth/ blog.git' hint: Updates were rejected because the tip of your current branch is behind hint: its remote counterpart. Integrate the remote changes (e.g. hint: 'git pull ...') before pushing again. hint: See the 'Note about fast-forwards' in 'git push --help' for details.
43. Should you rebase? Are you the only one working on the branch? Nope! Do you feel comfortable rebasing? Do you want to be? Only one way to learn! No worries Great! Go for it no yes no yes yes no
44. $ git push --force-with-lease Enumerating objects: 5, done. Counting objects: 100% (5/5), done. Delta compression using up to 8 threads Compressing objects: 100% (3/3), done. Writing objects: 100% (3/3), 358 bytes | 358.00 KiB/s, done. Total 3 (delta 2), reused 0 (delta 0) remote: Resolving deltas: 100% (2/2), completed with 2 local objects. To github.com:greggroth/blog.git + 2a0cd74...9adde05 add_posts -> add_posts (forced update)
46. GitHub’s Squash Merge
47. Accessible Accurate Succinct
48. @greggroth greggroth@gmail.com Gregg Rothmeier
49. Further Reading Interactive Tutorials Learn Git Branching Merging vs. Rebasing Blog Posts Tim Pope: A Note About Git Commit Messages Force with Lease The Golden Rules of Code Documentation Git Editor Integrations VS Code: GitLens Atom: Better Git Blame Vim: Vim-Fugitive Emacs: Magit