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

Documentation Tradeoffs and Why Commit Messages are Worth Spending Time On

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.

Cf9418e41c844d90cbd29e9061f7ba9c?s=128

Gregg Rothmeier

November 14, 2018
Tweet

Transcript

  1. Documentation Tradeoffs and Why Commit Messages are Worth Spending Time

    On 
 
 Greggory Rothmeier @greggroth Stitch Fix
  2. None
  3. Accurate Accessible # outputs "Hello"

  4. None
  5. None
  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
  37. None
  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)
  45. None
  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