Commit Messages to the Rescue!

by Ajina Slater

Slide 1

Slide 1 text

doodling.dev @doodlingdev https://xkcd.com/1296/

Slide 2

Slide 2 text

doodling.dev @doodlingdev Commit messages To the rescue

Slide 3

Slide 3 text

doodling.dev @doodlingdev Aji Slater he/him snapsheet My name is aji, A..J..I.. say it with me. The entire room sounds disappointed in me now I’m comfortable. My pronouns are he/him My website is in the upper left, and my twitter in the upper right. If twitter is a thing you do, and I 100% understand if you just. can’t. I know you have a choice in conference talks, and I want to thank you for being here.

Slide 4

Slide 4 text

doodling.dev @doodlingdev I work for a company called Snapsheet based in Chicago. We’re not unleashing the world’s creativity or anything.. I don’t honestly have a pithy one liner to explain what we do, but a story from a friend of mine, Brett, is the best way to describe it. … So technically our customers are the insurance companies, and we’re streamlining processes, saving millions of dollars, increasing eﬃciency, but it’s what we can do for the people like Brett that make it exciting for me. Here is where I insert the obligatory “we’re hiring” statement. Come work with me and let’s make beautiful commit messages together.

Slide 5

Slide 5 text

Slide 6

Slide 6 text

doodling.dev @doodlingdev Once upon a time… I gave a lightning talk version of this before, and I wanted to set up some of the situations in which commit messages could save your bacon. So I came up with a story about a workplace that could have been helped by good message practice. When looking for what pictures to put on my slides during this story, I reached for Dr Seuss imagery.

Slide 7

Slide 7 text

doodling.dev @doodlingdev I especially liked it because the ﬁsh could be the project manager. That.. felt right to me. So I started looking at the pictures.. and thinking, I’m going to give this talk at Railsconf… why not go all out? So I present to you..

Slide 8

Slide 8 text

doodling.dev @doodlingdev Git add, Git rm. Git commit Minus m! by Dr Seuss Deﬁnitely not by dr Seuss

Slide 9

Slide 9 text

doodling.dev @doodlingdev Git add, Git rm. Git commit Minus m! by Dr Seuss NOT Deﬁnitely not by dr Seuss

Slide 10

Slide 10 text

doodling.dev @doodlingdev An E-commerce site on AWS is a good enough scene for our story, I guess

Slide 11

Slide 11 text

doodling.dev @doodlingdev They employed devs much more than a few but i'd like to speak of thing one and thing two now thing one took some work from their burn-it-down chart seems a bug had been found in the site's shopping cart.

Slide 12

Slide 12 text

doodling.dev @doodlingdev even through all the planning, down deep in Rails magic requests had timed out, causing dips in their traﬃc Thing One raced to make known what was causing the fault sweating, anxious the server might catch ﬁre'n halt

Slide 13

Slide 13 text

doodling.dev @doodlingdev For a week without sleep, many cans of La Croix, "At long last I've uncovered our one tragic flaw!" With git blame we find out that Thing 2 wrote the class that for the last week was a pain in the ...... workflow

Slide 14

Slide 14 text

doodling.dev @doodlingdev now, it's readable.. tested.. but somethings amiss no one class should employ as much logic as this

Slide 15

Slide 15 text

doodling.dev @doodlingdev it made sense at the time, said thing 2 un-repenting and you KNOW all of MY code is self documenting "so you say," said Thing One, "but it needs a refactor." "Now help me ﬁnd out just what that method is after.

Slide 16

Slide 16 text

doodling.dev @doodlingdev "Seems like dead code to me, not much more than obstruction." Then their ﬁx was merged in, and they pushed to production.

Slide 17

Slide 17 text

doodling.dev @doodlingdev But their sigh of relief only lasted a ﬂash. never before had a site started crashing so fast. Looking at server logs their heart beats all quicken, "Hey I wonder if we could ask that Sean Griﬃn?"

Slide 18

Slide 18 text

doodling.dev @doodlingdev "He maintained Active Record, his opinion I trust." "Nah! He'll just tell us we should have used Rust."

Slide 19

Slide 19 text

doodling.dev @doodlingdev so call Aaron Patterson!

Slide 20

Slide 20 text

doodling.dev @doodlingdev call DHH! We're hemorrhaging money all over the place! As our devs contemplate the lost data and sales, think! When code loses context, apps run ...oﬀ the Rails.

Slide 21

Slide 21 text

doodling.dev @doodlingdev OK! Fun’s over. Down to business. Commit messages. We all do them, and like TDD we think they’re important but probably cut some corners here and there. I don’t want to stand up here and tell you you’re all doing something wrong..

Slide 22

Slide 22 text

doodling.dev @doodlingdev Because you’re not. But you might not be getting the most out of your commit messages

Slide 23

Slide 23 text

doodling.dev @doodlingdev Because you’re not. But you might not be getting the most out of your commit messages

Slide 24

Slide 24 text

doodling.dev @doodlingdev We’re all committed In general, version control is something that's taught fairly early on in learning to code. So the concepts need to be imparted in uncomplicated ways, and I bet that I can name a few.

Slide 25

Slide 25 text

doodling.dev @doodlingdev Its a save point, like in a video game

Slide 26

Slide 26 text

doodling.dev @doodlingdev Its a moment captured in time

Slide 27

Slide 27 text

doodling.dev @doodlingdev Its saving your work as you go along Like those or not, I'm fairly conﬁdent there wasn't much time spent on it, and we just used -m

Slide 28

Slide 28 text

doodling.dev @doodlingdev At the time, either when you're ﬁrst learning coding, or ﬁrst learning git, there's a lot to take in. Git is.. a little inaccessible at best.. so simplifying the steps is important to help learn. So we're shown `-m` and told to write a brief description and move on.

Slide 29

Slide 29 text

doodling.dev @doodlingdev Especially because if we typed git commit without the -m we were going to get stuck in a twilight zone from which there is no escape

Slide 30

Slide 30 text

doodling.dev @doodlingdev Especially because if we typed git commit without the -m we were going to get stuck in a twilight zone from which there is no escape

Slide 31

Slide 31 text

doodling.dev @doodlingdev Git commit was going to land us in VIM

Slide 32

Slide 32 text

doodling.dev @doodlingdev Much like I've seen the one true light, and use VIM as my daily-driver now that I have more familiarity, I've circled back around to git and commit messages.

Slide 33

Slide 33 text

doodling.dev @doodlingdev Because when these messages aren't thought about as a tool, but as a hindrance to work, or as a chore that we have to do that doesn't matter.. we end up with messages that are…

Slide 34

Slide 34 text

Slide 35

Slide 35 text

doodling.dev @doodlingdev Unhelpful

Slide 36

Slide 36 text

doodling.dev @doodlingdev Incredulous

Slide 37

Slide 37 text

doodling.dev @doodlingdev Maybe a bit on the nose..

Slide 38

Slide 38 text

doodling.dev @doodlingdev Even desperate

Slide 39

Slide 39 text

doodling.dev @doodlingdev Dishonest

Slide 40

Slide 40 text

doodling.dev @doodlingdev Depressing

Slide 41

Slide 41 text

doodling.dev @doodlingdev downright belligerent

Slide 42

Slide 42 text

doodling.dev @doodlingdev I’ve got nothin’

Slide 43

Slide 43 text

doodling.dev @doodlingdev I listen to a podcast, "The Bike Shed," and in days gone by it was hosted by Sean Griﬃn and Derek Prior, and somewhere in there, who remembers when...

Slide 44

Slide 44 text

doodling.dev @doodlingdev ...Sean started to talk about what a good commit message means, and how it can save you from bad situations I thought to myself, alright, this is a guy who talks about complicated code concepts like its nothin'.. and so often I don't know what he's talking about,

Slide 45

Slide 45 text

doodling.dev @doodlingdev but commit messages? Here's a bit of wisdom from this programming celebrity that I can put into practice.

Slide 46

Slide 46 text

doodling.dev @doodlingdev I know Kung fu So I started to look into commit messages. I read some blogs, a forum post or two, plenty of stack overﬂow questions, and a few pieces of advice rose to the top time and again

Slide 47

Slide 47 text

doodling.dev @doodlingdev 1. Use imperative tense 2. Start with a capital letter 3. Don’t end with a period 4. Keep it < 75 characters 5. Just use -m Show of hands, how many people have heard rules like these? and use them? how many people are seeing these ideas for the ﬁrst time? Some of these have reasons behind them... keep the subject short because git will truncate at around 50 characters.

Slide 48

Slide 48 text

doodling.dev @doodlingdev That’s 17.85% of a tweet Capital Letter, Period, the ?tense? you use...That's all just tabs or spaces. There's a convention we gravitate to (these conventions) but if your team or your project prefers something else, and has a diﬀerent style guide? Go for it.

Slide 49

Slide 49 text

doodling.dev @doodlingdev You do you And -m? Well we'll see why that shortcut is the same as an ice cream breakfast. It's nice at the time, but it's not going to help you get through the day.

Slide 50

Slide 50 text

doodling.dev @doodlingdev Speak for yourself

Slide 51

Slide 51 text

doodling.dev @doodlingdev The road Most travelled Let's take a moment and look at well intentioned commit messages I pulled from Github Again, please with a show of hands, how many of you have written a commit message like... this?

Slide 52

Slide 52 text

doodling.dev @doodlingdev How about this…

Slide 53

Slide 53 text

doodling.dev @doodlingdev or..

Slide 54

Slide 54 text

doodling.dev @doodlingdev What do these examples have in common?

Slide 55

Slide 55 text

doodling.dev @doodlingdev Poor life choices? They all follow those canonical rules, don't they. They might enforce stylistic consistency, but they're addressing the wrong things. Those examples all had something else in common..

Slide 56

Slide 56 text

doodling.dev @doodlingdev No body Every last one of those did not include a body to the commit message. The habit of not using message bodies is so prevalent, that I bet there are some developers out there who are capable, smart, great developers.. that have NEVER written a commit message body. There might be some at this conference, or in this room.

Slide 57

Slide 57 text

doodling.dev @doodlingdev Hi And to you, if you're out there, I cannot wait to share the new perspective on this boring, common tool…because it absolutely can be a game. changer.

Slide 58

Slide 58 text

doodling.dev @doodlingdev Overused cliche We’ve seen some examples and it seems pretty easy to agree on what makes a commit message unhelpful, what goes into a good commit message?

Slide 59

Slide 59 text

doodling.dev @doodlingdev Overused cliche We’ve seen some examples and it seems pretty easy to agree on what makes a commit message unhelpful, what goes into a good commit message?

Slide 60

Slide 60 text

doodling.dev @doodlingdev This is from an open source project by Thoughtbot called Clearance, with the subject line “Use route independent password reset redirect” and the body: … Concise but descriptive subject In two sentences this message conveys * The problem that required a change to be made * The intention of the code originally and therefore what the change is aiming for * References the main point of the solution.

Slide 61

Slide 61 text

doodling.dev @doodlingdev This is the little commit message that could. So much conveyed, with only as much text as it needs. This is more to type than 50 character -m message, but wouldn’t you already have this kind of information in your head if you had just made this change? There’s not a lot of extra work to make this happen.

Slide 62

Slide 62 text

doodling.dev @doodlingdev Let’s take a look at an example from the rails repo.

Slide 63

Slide 63 text

doodling.dev @doodlingdev Fix secret_key_base for Railties This was missed in the security ﬁx for local dev. CI doesn’t have a tmp directory in the apps built for testing so these end up failing. This adds the secret_key_base so we don’t need to generate one.

Slide 64

Slide 64 text

doodling.dev @doodlingdev This talks about the problem being ﬁxed, even where and how the bug was introduced. That can certainly be useful. Mentions what this commit adds, and why. Again, this is less than the amount of information that you would share with someone who walked by your desk and asked what you were working on.. but it gives us a LOT to work with if we’re thinking of changing the underlying code here.

Slide 65

Slide 65 text

doodling.dev @doodlingdev What made those messages better than some of the others we’ve looked at? [click] context. Why is context important? Well to illustrate my point, I'm going to go back to a Dr Seuss story,

Slide 66

Slide 66 text

doodling.dev @doodlingdev Context What made those messages better than some of the others we’ve looked at? [click] context. Why is context important? Well to illustrate my point, I'm going to go back to a Dr Seuss story,

Slide 67

Slide 67 text

doodling.dev @doodlingdev “Dr. Seuss” == “Theodore Geisel” #=> true not a seussical poem, but a story about Theodore Geisel (his real name) and one of his stories, Horton hears a who

Slide 68

Slide 68 text

doodling.dev @doodlingdev In which, an elephant named Horton vows to protect a tiny civilization ﬂoating on a spec of dust, met with ridicule from the other animals who can't or won't hear them. Horton proclaims "A person's a person no matter how small." Here's some context for you.

Slide 69

Slide 69 text

doodling.dev @doodlingdev Theodore Geisel was born in 1904, and like many white people of the time was pretty darned racist. I'm not going to put those images on screen, but famously he drew troubling images of Japanese citizens in the run up to World War II as a political cartoonist, amongst many other examples.

Slide 70

Slide 70 text

doodling.dev @doodlingdev But after the war, he travelled to Japan and met the people there, saw their relationship with the American Occupation, and heard their direct experience with nuclear weapons... and wrote Horton Hears a who as an allegory about the war. Some lines in there are straight up a reference to the atom bomb falling out of the sky.

Slide 71

Slide 71 text

doodling.dev @doodlingdev He also drew this cartoon.. it says.....

Slide 72

Slide 72 text

doodling.dev @doodlingdev Without the context, Horton is a silly book with a good message, with context it becomes one man's attempt to admit to the wrongs of his past attitudes in a very public way, and inﬂuence others to realize the same mistakes in themselves, or at least inoculate the youngins as best he could.

Slide 73

Slide 73 text

doodling.dev @doodlingdev Code Context Just as a work of art cannot be fully understood without context, code can be diﬃcult to impossible to wrap your head around without it.

Slide 74

Slide 74 text

doodling.dev @doodlingdev Who What Where When How The commit itself is going to tell you Who, What, Where, When, How.. but it's missing WHY. Its a blessing and a curse of programming that there are a million diﬀerent ways to solve every problem. It's less like engineering and math, and more like creative writing.

Slide 75

Slide 75 text

doodling.dev @doodlingdev Software Craftsman novelist We're constantly making decisions that have consequences to the future, and there's always a reason that we make the decisions we do. Record that reason in a commit message, because you or someone else might need it. How many times have you looked into a ﬁle that you didn't write only to think, "Why does this look like this?"

Slide 76

Slide 76 text

doodling.dev @doodlingdev Wouldn't it be great if we could hover over a line of code in our editors and read a note explaining exactly why a thing looks the way it does?

Slide 77

Slide 77 text

doodling.dev @doodlingdev Rhetorical Question You can, here it is in VSCode

Slide 78

Slide 78 text

doodling.dev @doodlingdev This is an extremely popular extension called Git Lens. This ﬁle is in the Rails source code, ActiveRecord, you can see the module name. Lets jump down a few lines and hover the mouse on line 44.. Have you ever had an annotated Shakespeare book before? How about annotated source code.. you ALREADY HAVE IT Who is all this context for, anyway?

Slide 79

Slide 79 text

Slide 80

Slide 80 text

doodling.dev @doodlingdev Do unto Others *Other Developers* who are changing this code, or using this API, or debugging an issue anyone who might write something that executes our code in the future.

Slide 81

Slide 81 text

doodling.dev @doodlingdev But aji… counterpoint: what if i'm the only one working on this?

Slide 82

Slide 82 text

doodling.dev @doodlingdev You are other developers Great! "Other Developers" can mean you in the future.

Slide 83

Slide 83 text

doodling.dev @doodlingdev Code Review To properly review code, you're going to need more than just seeing the change. Especially if you're using a tool that truncates a diﬀ, the reviewer might not even be seeing all the code that's aﬀected by the change.

Slide 84

Slide 84 text

doodling.dev @doodlingdev Do you see there on the left, [click] the line numbers go from 120 to 167. 47 lines of hidden code. Who knows what could be in there without opening each and every fold.

Slide 85

Slide 85 text

doodling.dev @doodlingdev Do you see there on the left, [click] the line numbers go from 120 to 167. 47 lines of hidden code. Who knows what could be in there without opening each and every fold.

Slide 86

Slide 86 text

doodling.dev @doodlingdev But aji… “counterpoint: that's what the PR comment is for.” 100% agree. That means you're already thinking that context is important, so why wouldn't you save it in the history instead of throwing it out when the code gets merged?

Slide 87

Slide 87 text

doodling.dev @doodlingdev Makes the dream Work Has anyone ever searched for something because you're stuck, only to ﬁnd a blog post from one of your colleagues, or even yourself, that gives you the answer? You can have that without googling, or if your internet is down [sign of the cross] with rich messaging.

Slide 88

Slide 88 text

doodling.dev @doodlingdev Cogito ergo Summary What's going to be easier to capture, context while you're closer to your thoughts, or a summary at the end of feature work after the fact? Its the same with TDD, writing tests up front and as you work, or going back in and struggling to cover all your bases.

Slide 89

Slide 89 text

doodling.dev @doodlingdev The laziness Argument I'm willing to admit that it's what won me over to actually *doing* TDD instead of just thinking its a good idea. When you're in the middle of feature development, you have all the energy of an exciting new task. And if we write our thoughts in the git history as we go, we can leverage that immediacy and capture helpful information for the project's future developers.

Slide 90

Slide 90 text

doodling.dev @doodlingdev Tooling ftw And tooling makes it easy to copy out any relevant information for code review into the PR.

Slide 91

Slide 91 text

doodling.dev @doodlingdev Less Is more The body of a commit message doesn't need to be a novel, or an entire page of documentation. The explanation should match the size of the context to share. What do we write?

Slide 92

Slide 92 text

doodling.dev @doodlingdev Public interface? If it’s part of a public interface, how could it be used or extended? What's relying on it not to change?

Slide 93

Slide 93 text

doodling.dev @doodlingdev Convention over Confusion We're Rails developers, we love conventions. We can all speak more or less the same language, and it should be easy for new developers to come onto a project if it all looks "Railsy" enough. Did something need to go against a convention for some reason?

Slide 94

Slide 94 text

doodling.dev @doodlingdev Cross Contamination Is there a non-obvious side eﬀect that falls out of the change?

Slide 95

Slide 95 text

doodling.dev @doodlingdev Frankenstein’s Docs This never happens but, did the actual execution of a library not line up with the documentation?

Slide 96

Slide 96 text

doodling.dev @doodlingdev It’s dangerous To go alone Are they any gotchas this code introduces? Are there any pitfalls that you saw when you were up to your elbows in this subsystem that would be good to know about in the future? think what precise domain knowledge you have *right then* that you want to remember.

Slide 97

Slide 97 text

doodling.dev @doodlingdev Flying Solo Try to write a message that will make sense without seeing the code. Not to replicate the code method for method, but if reading the git logs without the code open makes sense, the history becomes a much more useful document.

Slide 98

Slide 98 text

doodling.dev @doodlingdev My emotional Support commit Is there an external resource that applies? Link to - a ticket - a feature spec or user story - PR comments - Slack discussions can be deep linked - Resources you used: stack overﬂow answers, blog posts, videos, documentation, or speciﬁcations. But remember that links aren’t forever, the message should still make sense.

Slide 99

Slide 99 text

doodling.dev @doodlingdev Not another learning experience… We all refer to old code as a reference from time to time. "How did I solve this last time?" A little explanation and you're leaving breadcrumbs about how a design pattern, library or technique worked or didn't work, you're able to be one step ahead next time.

Slide 100

Slide 100 text

doodling.dev @doodlingdev Tag Team I've had some success with tagging my messages. Not git's tags, plain text tags to search either with GitHub's search box or with git log on the command line. an example...

Slide 101

Slide 101 text

doodling.dev @doodlingdev $tagname I use this convention when it’s some piece of work I might want to refer back to, and I try to give it a good name, but y’know.. only two hard problems…

Slide 102

Slide 102 text

doodling.dev @doodlingdev I’m in a repo of code for a workshop I led, and I think what I need is near the beginning, so I’ll log in reverse…

Slide 103

Slide 103 text

doodling.dev @doodlingdev I’m in a repo of code for a workshop I led, and I think what I need is near the beginning, so I’ll log in reverse…

Slide 104

Slide 104 text

doodling.dev @doodlingdev Well I didn’t see it, so we’ll try to grep. Because the command is a regex after the =, we have to escape the ‘$’ Here’s the syntax for the command, ——grep=query

Slide 105

Slide 105 text

Slide 106

Slide 106 text

doodling.dev @doodlingdev git log - -grep= Well I didn’t see it, so we’ll try to grep. Because the command is a regex after the =, we have to escape the ‘$’ Here’s the syntax for the command, ——grep=query

Slide 107

Slide 107 text

doodling.dev @doodlingdev git log - -grep= There it is!

Slide 108

Slide 108 text

doodling.dev @doodlingdev git log - -grep= There it is!

Slide 109

Slide 109 text

doodling.dev @doodlingdev Unpopular opinion self-documenting, completely self-contained context-free code is an unrealistic myth, and at worst an excuse not to try.

Slide 110

Slide 110 text

doodling.dev @doodlingdev Don’t @ me Even if you're using a tool like yard, or jsdoc, (both of which I really like) to generate API documentation, that's just adding more what.

Slide 111

Slide 111 text

doodling.dev @doodlingdev Right tool Right place Right time And why we wrote some code one way isn't necessarily going to be helpful for someone looking up what arguments a function takes, so "why" doesn't go there. but It can be helpful for someone who is making a change to the code.

Slide 112

Slide 112 text

doodling.dev @doodlingdev Out of Sync api docs and code comments don't stay in sync with the code as written, but commit messages persist exactly the same length of time as the code they describe. because new code necessarily changes the messages.

Slide 113

Slide 113 text

doodling.dev @doodlingdev Home free Change your code and update docs for free

Slide 114

Slide 114 text

doodling.dev @doodlingdev In practice so we've talked about why we want to write better messages, and how we can assemble a useful git history. It sounds like we're going to get to know our way around some parts of git that might be unfamiliar.

Slide 115

Slide 115 text

doodling.dev @doodlingdev Because treating the commit history as a kind of documentation requires a little more thought towards what commits you leave behind.

Slide 116

Slide 116 text

doodling.dev @doodlingdev Because treating the commit history as a kind of documentation requires a little more thought towards what commits you leave behind.

Slide 117

Slide 117 text

doodling.dev @doodlingdev Git has a lot of baked in tools to help us accomplish just that. Like the message template.

Slide 118

Slide 118 text

doodling.dev @doodlingdev Many of us are probably familiar with this message, it’s what appears when you start a new commit from the command line. This is customizable. It doesn't have to be the same as this. If a teams has a standard of what should be included in a message, we can leave prompts for ourselves to ﬁll in.

Slide 119

Slide 119 text

doodling.dev @doodlingdev Remember the default message, any line with an # will be ignored. On line 12 we see “Closes.” [click] With an issue number, Github will close the related issue once this commit is merged to the default branch

Slide 120

Slide 120 text

Slide 121

Slide 121 text

doodling.dev @doodlingdev close fix resolve Any of these keywords will work for GitHub, close, closes, closed etc. If you don’t use github, many other tools have similar features as well.

Slide 122

Slide 122 text

doodling.dev @doodlingdev This example has width guides in case we can’t set a hard wrap. [click] Also includes a reference to tags in the subject line. This is a convention popular in projects like Angular, Electron and other places. [click] It’s called ‘conventional commits’ I’m not going to touch on that here, but the super simpliﬁed version: to make commit messages both more human readable and helpful, but also machine parseable.

Slide 123

Slide 123 text

Slide 124

Slide 124 text

doodling.dev @doodlingdev To make this template thing happen, we make a plain text ﬁle. It'll look like... Yup. Just that. Whatever we want to have at the top, write it in. Save this wherever you want, perhaps you have a dotﬁles management system? I'll happily geek out about that in the hall after if anyone wants. You know who you are.

Slide 125

Slide 125 text

doodling.dev @doodlingdev Tell git where to find the template in the gitconfig. That's a file that lives in the home directory, [click] Or for windows…

Slide 126

Slide 126 text

doodling.dev @doodlingdev ~/.gitconfig Tell git where to find the template in the gitconfig. That's a file that lives in the home directory, [click] Or for windows…

Slide 127

Slide 127 text

doodling.dev @doodlingdev ~/.gitconfig C:\ProgramData\Git\config Tell git where to find the template in the gitconfig. That's a file that lives in the home directory, [click] Or for windows…

Slide 128

Slide 128 text

doodling.dev @doodlingdev there are plenty of configuration options possible in here, but the one we care about right now is this… Commit in brackets is the section heading Template equals and then the path to the file we just made If this is the only configuration in this file, its totally valid.

Slide 129

Slide 129 text

doodling.dev @doodlingdev And that is commit templates.

Slide 130

Slide 130 text

doodling.dev @doodlingdev And that is commit templates.

Slide 131

Slide 131 text

doodling.dev @doodlingdev

Slide 132

Slide 132 text

doodling.dev @doodlingdev

Slide 133

Slide 133 text

doodling.dev @doodlingdev wohpos Sometimes small changes need to happen after a commit, whitespace ﬁx, or we want to change a variable name, but we’ve written a really great message. Insightful, future-aware comment.

Slide 134

Slide 134 text

doodling.dev @doodlingdev Sometimes small changes need to happen after a commit, whitespace ﬁx, or we want to change a variable name, but we’ve written a really great message. Insightful, future-aware comment.

Slide 135

Slide 135 text

doodling.dev @doodlingdev What’s that going to do to the messages for that ﬁle?

Slide 136

Slide 136 text

doodling.dev @doodlingdev Whoops What’s that going to do to the messages for that ﬁle?

Slide 137

Slide 137 text

doodling.dev @doodlingdev Kind of a contrived example, but here’s a bit of code. [click] We see there are some typos. Autocomplete makes that easy sometimes, means it’s valid code, but it’s gotta be ﬁxed. [click] If we ﬁx the typo and commit again.. what are the commit messages going to look like?

Slide 138

Slide 138 text

Slide 139

Slide 139 text

Slide 140

Slide 140 text

doodling.dev @doodlingdev Good messages on all the lines, but the typo ﬁx overrides it on some fairly important places. Sometimes there are changes that aren’t worth a commit message, but there needs to be a commit. Or maybe there’s a commit you need for development that doesn’t need to be pushed up or merged.

Slide 141

Slide 141 text

Slide 142

Slide 142 text

doodling.dev @doodlingdev right? You don't have to re-type or copy paste messages, there's a command to merge commits, and we can sweep that typo or WIP under the rug, no one needs to know it ever existed.

Slide 143

Slide 143 text

doodling.dev @doodlingdev git rebase -i If you've had trouble with rebase in the past, that's alright, we don’t need to grok the concept in the same way with this technique, “-i” means this is interactive rebase and we're just going to change within our current branch This allows us a lot of ﬂexibility in manipulating the commit history, and it’s done by opening a text ﬁle in your chosen editor… more on that in a minute.

Slide 144

Slide 144 text

doodling.dev @doodlingdev This ﬁle is going to serve as a set of instructions to git on how it should handle each commit. We see they’re listed out in order, oldest to newest. * First is the action we want git to take for each commit, defaulting to “pick” * Second is the shortform hash that acts as id for the commit * Finally, the subject line of our commit message

Slide 145

Slide 145 text

doodling.dev @doodlingdev Note here the body of the messages are not displayed. Just the subject for now. Another reason why a descriptive subject line is important. Try messing around with the git history with a bunch of subject lines like “some changes to model” And helpfully the available actions we can use are listed below in the commented out portion. I’ve lightened some because today we’re going to cover those four only.

Slide 146

Slide 146 text

doodling.dev @doodlingdev First up is “pick”. It’s the default action for each commit, and it basically means, use this commit. Don’t do anything, replay it into the history just the way it is.

Slide 147

Slide 147 text

Slide 148

Slide 148 text

Slide 149

Slide 149 text

doodling.dev @doodlingdev Next is reword. Use commit, but edit the commit message. Lets take a look at what a reword action looks like in practice.

Slide 150

Slide 150 text

doodling.dev @doodlingdev Next is reword. Use commit, but edit the commit message. Lets take a look at what a reword action looks like in practice.

Slide 151

Slide 151 text

doodling.dev @doodlingdev Next is reword. Use commit, but edit the commit message. Lets take a look at what a reword action looks like in practice.

Slide 152

Slide 152 text

doodling.dev @doodlingdev Before we start, let’s take a look at the commit we want to change, it’s the last commit relative to where we are now, [click] so we use git log HEAD~ to mean show me the message on the commit right before HEAD We don’t need to memorize the content here to understand what happens next, so let’s continue

Slide 153

Slide 153 text

Slide 154

Slide 154 text

doodling.dev @doodlingdev We’ll use our git rebase -i to get started

Slide 155

Slide 155 text

doodling.dev @doodlingdev We’ll use our git rebase -i to get started

Slide 156

Slide 156 text

doodling.dev @doodlingdev First step is to change the text on the line of the commit we want to reword. Then save and close the ﬁle. Git will read in those instructions and proceed…

Slide 157

Slide 157 text

doodling.dev @doodlingdev First step is to change the text on the line of the commit we want to reword. Then save and close the ﬁle. Git will read in those instructions and proceed…

Slide 158

Slide 158 text

doodling.dev @doodlingdev

Slide 159

Slide 159 text

doodling.dev @doodlingdev

Slide 160

Slide 160 text

doodling.dev @doodlingdev Git opens a commit prompt, same as if it was a brand new commit, but prepopulated with the message that currently exists. We’re going to make a really obvious change to show what’s going on. [click] Note we’re not changing the subject here, but we could if we wanted to.

Slide 161

Slide 161 text

Slide 162

Slide 162 text

doodling.dev @doodlingdev Let’s log the same message and see what it looks like now [click] All changed! I’ll superimpose the old log..[click] And you can see, the commit hash has changed because the content of the commit changed in the message. But the date, everything else stays the same.

Slide 163

Slide 163 text

Slide 164

Slide 164 text

Slide 165

Slide 165 text

doodling.dev @doodlingdev Next is “squash,” I ﬁnd it the most useful for managing unnecessary commits, or creating commits that more succinctly encompass the work for a branch. [click] Because sometimes development needs more commits than we’ll need in master.

Slide 166

Slide 166 text

Slide 167

Slide 167 text

Slide 168

Slide 168 text

doodling.dev @doodlingdev I’m looking at these three commits Seems like they’re doing very similar things, and I want to have the messages and changes merged into one commit to push it up for code review.

Slide 169

Slide 169 text

Slide 170

Slide 170 text

Slide 171

Slide 171 text

doodling.dev @doodlingdev What I want to do is take the commits on lines 3 & 4, and merge them into the commit on line 2. When you label a commit for squashing, [click] it will be merged into the commit before it. So remember that. Squashes move UP

Slide 172

Slide 172 text

Slide 173

Slide 173 text

doodling.dev @doodlingdev And because the contents of the commit has changed, [click] We’ll amend the subject too Let’s see it in practice

Slide 174

Slide 174 text

doodling.dev @doodlingdev New subject line! And because the contents of the commit has changed, [click] We’ll amend the subject too Let’s see it in practice

Slide 175

Slide 175 text

doodling.dev @doodlingdev We’ll ﬁre up interactive rebase

Slide 176

Slide 176 text

doodling.dev @doodlingdev We’ll ﬁre up interactive rebase

Slide 177

Slide 177 text

doodling.dev @doodlingdev Same as before but now we choose squash. Save and quit.

Slide 178

Slide 178 text

doodling.dev @doodlingdev Same as before but now we choose squash. Save and quit.

Slide 179

Slide 179 text

doodling.dev @doodlingdev This ﬁle that is opened is where we tell git what to do with the messages, as three commits become one [click] Each message is delineated with a comment. [click] And each section consists of the commit’s subject, a blank line, and the message. If we did nothing, the new commit message would look just like this without the comments. [click] But it doesn’t seem necessary to me to keep the outdated subjects. I remove the comments too so I can see what the ﬁnished message will look like.

Slide 180

Slide 180 text

Slide 181

Slide 181 text

Slide 182

Slide 182 text

Slide 183

Slide 183 text

doodling.dev @doodlingdev The ﬁrst line will become our new subject, [click] and this doesn’t accurately reﬂect what this commit is changing, so we can update that as well.

Slide 184

Slide 184 text

doodling.dev @doodlingdev The ﬁrst line will become our new subject, [click] and this doesn’t accurately reﬂect what this commit is changing, so we can update that as well.

Slide 185

Slide 185 text

doodling.dev @doodlingdev And we’ll take a look at the new commit now that we’re all done. I’m going to use git log - - oneline to see a compact version of the log with only subjects

Slide 186

Slide 186 text

doodling.dev @doodlingdev And we’ll take a look at the new commit now that we’re all done. I’m going to use git log - - oneline to see a compact version of the log with only subjects

Slide 187

Slide 187 text

doodling.dev @doodlingdev and copy the shortcode to use for our git logging. Start the printout at that speciﬁc commit. [wait] and there it is.

Slide 188

Slide 188 text

doodling.dev @doodlingdev and copy the shortcode to use for our git logging. Start the printout at that speciﬁc commit. [wait] and there it is.

Slide 189

Slide 189 text

doodling.dev @doodlingdev Finally, “ﬁxup” which doesn’t need a whole runthrough, because ﬁxup merges UP, like squash, but the commit message is just deleted. This is perfect for those typos or whitespace commits.

Slide 190

Slide 190 text

Slide 191

Slide 191 text

Slide 192

Slide 192 text

doodling.dev @doodlingdev The never- Ending story I could literally spend another hour up here going through git commands and minutia so if you wanted more of that, I sincerely hope you went to Chris Toomey’s incredible deep dive into git workshop on Wednesday

Slide 193

Slide 193 text

doodling.dev @doodlingdev As for me, I made a bold promise in the talk description that I would teach you how to do all of this git wrangling in an editor other than VIM

Slide 194

Slide 194 text

doodling.dev @doodlingdev Hold your Horses ﬁrst! I want to show you how to use VIM juuuust enough to not have to open another application… So you can stay in the terminal for all your message crafting needs.

Slide 195

Slide 195 text

doodling.dev @doodlingdev Git commit will likely drop you into VIM, yes. And that can be a scary place if you don’t know all of the arcane incantations required.

Slide 196

Slide 196 text

doodling.dev @doodlingdev Git commit will likely drop you into VIM, yes. And that can be a scary place if you don’t know all of the arcane incantations required.

Slide 197

Slide 197 text

doodling.dev @doodlingdev But you can handle committing, and message editing with three commands.

Slide 198

Slide 198 text

doodling.dev @doodlingdev But you can handle committing, and message editing with three commands.

Slide 199

Slide 199 text

doodling.dev @doodlingdev Nothing works the way you’re used to when you ﬁrst get into vim

Slide 200

Slide 200 text

doodling.dev @doodlingdev Nothing works the way you’re used to when you ﬁrst get into vim

Slide 201

Slide 201 text

doodling.dev @doodlingdev That’s because you’re in a mode for navigating the text, not editing. To edit you must enter insert mode.

Slide 202

Slide 202 text

doodling.dev @doodlingdev That’s because you’re in a mode for navigating the text, not editing. To edit you must enter insert mode.

Slide 203

Slide 203 text

doodling.dev @doodlingdev Press i to get into insert mode. Then you can type and move around the way you’re used to. Even with the arrow keys work here.

Slide 204

Slide 204 text

doodling.dev @doodlingdev Press i to get into insert mode. Then you can type and move around the way you’re used to. Even with the arrow keys work here.

Slide 205

Slide 205 text

doodling.dev @doodlingdev When you’re done editing, you’ll need to press escape. No mnemonic. Cancel out of insert mode by pressing escape.

Slide 206

Slide 206 text

doodling.dev @doodlingdev When you’re done editing, you’ll need to press escape. No mnemonic. Cancel out of insert mode by pressing escape.

Slide 207

Slide 207 text

doodling.dev @doodlingdev To complete the process you’ll type :wq Colon to enter a command, W to WRITE  and q to QUIT That’s i, type your message, escape, : write quit.

Slide 208

Slide 208 text

doodling.dev @doodlingdev To complete the process you’ll type :wq Colon to enter a command, W to WRITE  and q to QUIT That’s i, type your message, escape, : write quit.

Slide 209

Slide 209 text

doodling.dev @doodlingdev now, you know vim

Slide 210

Slide 210 text

doodling.dev @doodlingdev now, you know vim

Slide 211

Slide 211 text

doodling.dev @doodlingdev One of us! One of us! But if you feel the need to use another editor, all we’re going to have to do is open up that gitconﬁg and add another setting.

Slide 212

Slide 212 text

doodling.dev @doodlingdev Core as the heading Editor equals then the command to open your editor from the command line. Sometimes you’re going to have to install that command, it should be in your editor’s FAQ or the like if you don’t have it already set.

Slide 213

Slide 213 text

doodling.dev @doodlingdev If you use a GUI editor, deﬁnitely for Atom, VSCode, or Sublime, you’ll need to append - - wait to the command, or it will only open a blank ﬁle.

Slide 214

Slide 214 text

doodling.dev @doodlingdev git config - -global core.editor “atom - -wait” Or you can run this command from the command line once.

Slide 215

Slide 215 text

doodling.dev @doodlingdev git config - -global core.editor “atom - -wait” I am basically out of time, but I want to let you know I will be tweeting out a copy of these slides, as well as a post about all of the things I didn’t get to cover.

Slide 216

Slide 216 text

doodling.dev @doodlingdev git config - -global core.editor “atom - -wait” because after running my talk for the ﬁrst time, I realized it was two hours long.. and some things just had to go.

Slide 217

Slide 217 text

doodling.dev @doodlingdev git config - -global core.editor “atom - -wait” Things like a mini review of my opinions on plugins for most of the major editors and more useful git commands for reading and managing commit history.

Slide 218

Slide 218 text

doodling.dev @doodlingdev I apologize for not being able to get it all together for you,

Slide 219

Slide 219 text

doodling.dev @doodlingdev but we were woken up this morning by a call from our doggie daycare that they had to rush my little boy to the vet, he’s ﬁne, but its obviously left me with less time than I thought I had. So, I’m not religious or anything, but hugs at a distance for Henson please.

Slide 220

Slide 220 text

doodling.dev @doodlingdev I hope you all have formed or started to form your own idea of what a "good" commit message is.

Slide 221

Slide 221 text

doodling.dev @doodlingdev I think you’ll ﬁnd the answer to "how do we write good commit messages?" is diﬀerent in every team, every person, and every situation, while still considering its usefulness

Slide 222

Slide 222 text

doodling.dev @doodlingdev I'm going to close with my answer to that. A line that is very quickly becoming my personal catchphrase..

Slide 223

Slide 223 text

doodling.dev @doodlingdev I'm going to get it tattooed, written on my gravestone & hire a skywriter.

Slide 224

Slide 224 text

doodling.dev @doodlingdev The answer, like the answer to most things, is with empathy.

Slide 225

Slide 225 text

doodling.dev @doodlingdev Commit with Empathy Empathy for you teammates, empathy for yourself, empathy for developers of the future you might never meet.

Slide 226

Slide 226 text

doodling.dev @doodlingdev Commit with Empathy Someone earlier in the week said something that i LOVE. When I told them about my talk, they called me a 'commit message archaeologist'.

Slide 227

Slide 227 text

doodling.dev @doodlingdev So I encourage you to be commit message archaeologists, and at the same time.. to leave something behind that can be useful for fellow archaeologists.

Slide 228

Slide 228 text

doodling.dev @doodlingdev So I encourage you to be commit message archaeologists, and at the same time.. to leave something behind that can be useful for fellow archaeologists.

Slide 229

Slide 229 text

doodling.dev @doodlingdev And even if you can't convince everyone else you work with that commit messages should be more than

Slide 230

Slide 230 text

doodling.dev @doodlingdev And even if you can't convince everyone else you work with that commit messages should be more than

Slide 231

Slide 231 text

doodling.dev @doodlingdev if you're one in a team of ﬁve, then taking up the mantle of meaningful commit messages still means that you'll have 20% more of a chance that a commit message can save your bacon, too. And once your message saves someone else.. maybe it'll be a 40% chance, then 60 So I’ll leave you with that thought and a paraphrased quote

Slide 232

Slide 232 text

doodling.dev @doodlingdev Be the change you want to see in the code Thank you