I am a Web Developer, formerly a theatre professional and prop construction wizard who began learning fabrication and sculpture in my study of Interdisciplinary Electronic Art. From early on, I was interested in creating experiences for those that interacted with my art, and used technological tools to achieve them.I am continually curious about how humans interact with technology. I built props that would combine electronics with circus performance, and worked with the most cutting-edge performers in that emerging field. My decision of new project was often based on the question "will I learn a new skill here?" I seek out new challenges that are outside of my comfort zone, and endeavor to never be afraid to tackle a situation I haven't yet faced.Finding myself more invested in the electronic half of my entertainment career drew me to explore software in depth for my own learning, and eventually to Dev Bootcamp for a professional education.The world is moving more and more online and becoming increasingly integrated with tech in everyday life. It's that wave moving towards the internet and connectivity that I strive to tap into. Creating intuitive, enjoyable experiences with native web applications that can make lives more fulfilled and joyful.I am a fan of the oxford comma.View the profile
About the talk
RailsConf 2019 - Commit Messages to the rescue! by Christopher "Aji" Slater
What if I told you there is more to a commit message than "-m"? Like source code time capsules, those pesky formalities can deliver wisdom and perspective about any code from the best possible source, the developer who just wrote it! Explore new facets of these time traveling rubber duck opportunities to increase their usefulness tenfold. Tools like templates, linters, hooks, and automation. Hear what Dr. Seuss can teach us about git, and don't miss the most helpful morsel of git customization around... how to open a new message in an editor other than vim!
Okay, so maybe the talk messages to the rescue. My name is a g so it's pretty short name. But a lot of people still have trouble with it smells right up there a j i n you say it like that and just so that you never forget who I am. I'd like you all to do it along with me. Okay, I'll spell it out. AJ I and I want to hear you. Say hi G. Okay good. We didn't do the snap. So one more time if you would humor me please a j i a g excellent and like a disappointed in me. Good thing I'm comfortable now
though. So my pronouns are he him website is in the upper left Twitter is in the upper, right if Twitter's a thing that you do and I 100% understand if you just can't and I know that you have a choice in conference talks, and I want to thank you for being here with me. I work for a company called snapsheet based in Chicago where not unleashing the world's creativity or anyting and I don't honestly have a pissy one liner to explain what we do but a story from a friend of mine and I think is the best way to describe. It called an Uber went down. I stood outside waiting for the Uber stood
next to his motorcycle and they were pulled up and smashed right into his bike knocked it over. The Uber driver said oh no, it's okay, which is terrifying in and of itself you said? No, it's not that's my bike. And he anticipated weeks of go shopping around and body shops and having a fight with his insurance carrier and seeing which one he could get and if it would ever get fixed in months, but the next day he got a text from his carrier don't. Download our app took pictures of his damage with the phone and he had money in his account the next day. So technically our customers that the
insurance companies we're streamlining processes saving millions of dollars increasing increasing efficiency, but it's what we can do for the people like Brett that make it exciting for me. And here's where I insert the obligatory. We're hiring statement. Come work with me and let's make beautiful commit messages together. I give a lightning Talk version of this before and I wanted to set up some of the situations in which commit messages could really save your bacon. So I fabricated a story about a workplace that could have been helped by good message practice when looking at what pictures
to put on my slides during this story I reached for dr. Seuss imagery. I specially liked it because the fish could be the project manager and that just felt right to me. So I started looking at the pictures and thinking while I'm going to give this talk at railsconf. That's a little bit bigger than the other venue. Why not go all out. So I present to you get add get RM get to MIT minus m Definitely not by. Dr. Seuss. An e-commerce site on AWS is a good enough scene for our story. I guess they
employed devs much more than a few but I'd like to speak of Thing 1 and Thing 2 nothing one took some work from there burn it down chart seems a bug have been found in the site shopping cart, even through all the planning down deep in rails magic request set timed out causing dips in there traffic Thing 1 race to make known what was causing the faults sweating anxious the server might catch fire in halt for a week without sleep many cans of Lacroix uncovered are one tragic flaw only find out the thing to wrote the class that for the last week was a pain in our
workflow Now it's readable tested but something's amiss no one class should employees much love because this it made sense at the time said thing to on repenting and you know, all of my code is self-documenting. So you say said thing one, but it needs a reflector now help me find out just what that method is after seems like dead code to me. Not much more than obstruction. Then they're fixed was merged in and they push the production. I had so much fun doing this again. But their side relief only lasted a flash never before had a site
started crashing so fast looking at server logs their heartbeats all Quicken. Hey, I wonder if we could ask that Shawn Griffin. He maintained active record his opinion. I trust he'll just tell us we should have used rust. Call Aaron Patterson call. Dhh. We're hemorrhaging money all over the place as are devs contemplate the lost data and sales think when code loses context app run off the rails. Okay Fun's over down to business. Commit messages, we all do that. Thank you.
Give me messages. You know what I'll do them in it kind of like TD. We all agree that they're very important, but we probably cut some Corners here and there and I don't want to stand up here and tell you all that you're doing something wrong because you're not you might just not be getting the most out of your commits messages. In general Version Control the something that's out fairly early on in learning to code. So the concepts need to be in part of an uncomplicated ways and I bet I know a couple of those six savepoint like in a video game or a moment captured in time or
saving your work as you go along with it was like those are not I'm fairly confident that there wasn't too much time spent on it and we all just used a sham. At the time either when you're first learning coding or First Learning get there's a lot to take in get is a little inaccessible at best. So simplifying the steps is important to help learn. So we're shown dash cam told to write a brief description and move on especially because if we type get commit without the dash and we were going to get stuck in a Twilight Zone from which There Is No Escape, Yes, that's right. Get commit was
going to Landis and Vin. And now I'm much like I've seen the one true light and use them as my daily driver now that I have more familiarity. I've circled back around to commit messages and get Because when these messages aren't thought about as a tool but is a hindrance to work or is a chore that we have to do. That doesn't really matter. We end up with messages that are unhelpful. incredulous Maybe a bit on the nose. even desperate dishonest depressing downright belligerent Don't got nothing.
I like those that couple kiss didn't get translated into an emoji. So I listen to a podcast called the bike shed and in days gone by it was hosted by Shawn Griffin and Derek Pryor and somewhere in there who really remembers when Shawn started to talk about what a good commit message was and how it can save you from Bad situations. I thought to myself. All right. This is the guy who talks about complicated code Concepts like it's nothing and so often I have no idea what he is talking about but commit messages there's a bit of wisdom from this programming celebrity that I can put into
practice. So I started to look into commit messages are read. Some blogs are Forum poster to plenty of stack Overflow questions in a few piece of advice Rose to the top time and time again. Show of hands how many people who've heard or seen rules a lot like this. for any use them losantville down how many people are seeing these ideas for the first time? Some of these have reasons behind them. You keep the subject short because get get hovel truncated around 50 characters capital letter.
Hence you use those are all just tabs and spaces. There's a convention that we gravitate to probably those rules. But if your team or your project prefer something else has a different style guide will go for it. And a shemwell will 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. Let's take a moment. Look at some well-intentioned commit message that parole office GitHub again. Please have the show of hands how many of your retina commit message
like this? Or this one. What about this one? So what are all of these examples have in common? They don't follow those canonical rules. Don't they they might in for some stylistic consistency, but really they were addressing the wrong things because those examples all had something else in common. Every last one of those did not include a body to the commit message in 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 of this conference or even in this room. And to you if you're out there, I cannot wait to share this new perspective on this boring common tool because it absolutely can be a game changer. Now we've seen some examples and it seems pretty easy to agree on what makes a good what makes a commitment sajaan helpful. So what goes into a good commit message? This is SIA from an open source project. I thought code clearance with the subject line. I'll read this out cuz it might be hard to
see actual that's pretty big but use route independent password reset redirect body is using edit user password URL requires that particular path helper to exist. That's not necessarily the case since all we want to do is redirect to the same action. We can use URL for instead. It's a concise but descriptive subject in two sentences this message conveys the problem that required to change to be made the intention of the code originally and therefore With The Changes aiming for and references the main point of the solution. This is the little commit message that could so much conveyed
with only as much text as it needs. Sure. This is more to type than a 50 character Dash and message but wouldn't you already have this kind of information if your head in your head if you had just made this change, it's not really a lot of extra work to make this kind of thing happen. Let's take a look at an example from rails. Fix secret key base for rail ties. This was missed in the security fix for local data CI doesn't have a temp 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. This talks about the
problem being fixed even where and how the bug was introduced in this can certainly be useful mentions what this commit ads 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 him for thinking about under changing the underlying code. So what made those messages better than some of the others that we've looked at? context Why is contact so important illustrate my point I'm going to go back to a dr. Seuss story not
another poem. Sorry, but a story about Theodore Geisel, that's his real name and one of his stories Horton Hears a Who that Arielle thankfully left out of his life so that I could still do it. In which an elephant named Horton views vows to protect a tiny civilization that's floating on a speck of dust met with ridicule from the other animals who can't or won't hear them working for claims a person's a person no matter how small will you some contacts for you? Theodor Geisel was born in 1904 and like many white people of the time was pretty darn 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 political cartoonist amongst far too many other examples But after the war he traveled to Japan and met the people there saw the relationship with the American occupation and heard their direct experience with nuclear weapons. He wrote Horton Hears a Who as an allegory about the war some lines and there are straight references to the atom bomb falling from the sky. He also Drew this cartoon at the top it says what this country needs is a good mental insecticide, which is a
line of Americans coming up to Uncle Sam to have insecticide sprayed in their ear and forcing out the racial Prejudice bug. 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. He tried to influence others to realize the same mistakes in themselves or at the very least in knock you late the young uns as best as he could. This is a work of art cannot be fully understood without context code can be difficult to impossible to wrap your head around
without it. The committee itself is going to tell you who what where when how but it's missing why it's a blessing and a curse of programming that there are a million different ways to solve every problem. It's less like engineering and math and more like creative writing. We're constantly making decisions that have consequences to the Future and there's always a reason that we make the decisions that we do even if it's sometimes a little thin record because you or someone else might need it. But how many times have you looked into a file that you didn't write only to think this
look like this. Wouldn't it be great if we could hover over line of code not editors and read a note explaining exactly why I thing looks like the way it does. all you can Iridescent vs. Code Addison extremely popular extension cord get lens. This file is in the real Source Cota active record. You can see the model name on line three. We're going to jump down a few lines and however the mouse online 44 beautiful. Have you ever had an annotated Shakespeare book before it really opens up the text in a way that you probably have never experienced
it. How about annotated source code. You've already got it. Who's all this context for anyway? Other developers developers, we're changing this code or using this API or debugging an issue. Basically anyone who might write something that executes our code in the future. But what if I'm the only one working on this? Other developers can be in you in the future. To properly review code you're going to need more than just seeing the change especially for using a tool
that truncate sad if the reviewer might not even be seeing all the code that's affected by this change. If you see there on the left the line numbers go from 120 to 167 with 47 lines of Aiden code. Who knows what could be in there without opening each and every fold in the you want. Okay, but that's what the pr comment is for. 100% agree that means also that you're already thinking that context is important. So why wouldn't you save in the history instead of throwing it out with the code when it gets merge or when the code gets merch not with
that be bad. Has anyone ever searched for something because you're stuck only to find a blog post from one of your colleagues or even yourself that gives you the answer. Anybody definitely happen to me. You can have that without Googling or if your internet is down with Rich messaging. What's going to be easier to capture contacts while you're closer to your thoughts or summary at the end of Feature work after the fact it's the same thing with tdd writing test upfront and as you work or going back in and struggling to cover all your bases. Okay, I'm willing to admit that
this is what won me over to actually doing DDD instead of just thinking it was a good idea. When you're in the middle of future development. You have all the energy of an exciting new task and we write our thoughts in the get history as we go we can leverage that immediacy and capture helpful information for the project future Developers. And truly makes it easy to copy out any relevant information for code review and put it right there. And if you are you have to write it twice. 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 that you have to share so it'll be right. Well as part of a public interface, how could it be used or extended what's relying on it? If we're rails developers, we love conventions. We no speak more or less the same language and it should be easy for new developers to come on to a project if it all looks really enough did something need to go against the convention for some reason. Is there a non-obvious side effect that falls out of this change and really what does obvious even mean? I know okay, this never happens, but if it
did and the actual execution of a library didn't line up with the documentation. Are there any gachas 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 about what precise domain knowledge you have right then that you might want to remember. I tried to write a message that will make sense without seeing the code can be kind of difficult but don't need to replicate the code method for method or anything. But if
reading the get logs without the code open makes the map history becomes a much more useful document. Is there an external resource that applies link to a ticket or a feature speker user story PR comments lack discussions can be deep linked. I resources that you use that stack Overflow answers blog post videos documentation specification conference talks from cool guys with low tide. Remember that links aren't forever. The message should still make sense. We all refer to Old code as a reference from time to time.
How did I solve this the last time a little explanation and you're leaving breadcrumbs about how a design pattern a library or technique worked or didn't work you're able to be one step ahead next time. I've been a little success with tagging my messages not get Stags playing text tags to search either with GitHub search Boxer with get log on the command line little example here. 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, you know only too hard problems. So this is in a refill of code for a workshop by
Led, and I think what I need is near the beginning, so I'm going to log in reverse. I didn't see it there though. I so will try to try to grab through it because this command is a regex after the equal sign. We're going to escape the dollar sign and here's the Syntax for that. Come on, by the way. It's get log - - grep equals. What are you looking for? And there it is. Okay, self-documenting completely self-contained context-free code is an unrealistic meth and at worst. It's an excuse not to try. In a few shooting a tool like yard or JS. Which I
really like to generate API documentation. That's just adding more what? And why we wrote some code one way isn't necessarily going to be helpful for someone looking up what arguments of function takes so why doesn't really seem to go there but it can be helpful for someone who's making a change this code. API docs and code comments they don't stay in sync with the code AS written but commit messages persist exactly. The same length of time is the code they describe because new code necessarily changes those commit messages. Change the code update your docs for free.
So we've talked about why we want to ride better messages and how we can assemble a useful get history and it sounds like we're going to get to know our way around some parts of get that might be unfamiliar. Because it's treating the commit history as a kind of documentation requires a little more thought towards what commits that you leave behind. Get have a lot of baking tools to help us accomplish. Just that like a message template. When you guys are probably familiar with this message, it's what appears when you start a new commit from the command line. But this is
customizable. It doesn't have to be the same as this if a team has a standard of what should be included in a message we can leave prompts for ourselves to fill in. Remember the default message any line with the octothorpe will be ignored online 12. We see closes to with an issue number get help will close the related issue. Once this committee is merge to the default Branch any of these keywords actually work on GitHub close closes closed. If you don't use GitHub many other tools have their similar features as well. This example has with
guides in case we can't set a hard rap and also includes a reference to tags in the subject line. This is a convention popular in a lot of Open Source projects angular electron other places. It's called Convent. It's called conventional commits, and I'm not really going to touch on that here, but the super simplified version is to make commit messages both more human readable and helpful, but also Mission Impossible. So that thank you you okay where to find the template in the git config. That's a file that lives in the home directory.
Or if you're on Windows look something like that. There are plenty of configuration options that are possible in here. But the one that we're going to care about right now is this damn it in the brackets is the section heading template equals and on the path to the file that you just made if this is the only configuration in the file that's totally valid. that commit templates You can store those that maybe you have a. Files management system something like that. And if you want to kick out about that in the hall afterwards, I'll be there. You
know who you are. Sometimes small changes need to happen after a commit whitespace fix or we want to change variable name, but we've written a really great commit message insightful Futura where comment. What's that going to do for the messages for that file kind of a contrived example, okay, but here's a bit of code and that we see that there are some typos autocomplete make that easy sometimes right? It's ballad code still but it's got to be fixed. If we fix the typos and commit again, what are the commit message is going to look like if you
try to get Flame or read through line by line in your editor? Good messages on all the lines that the typo fix override it overrides it on some fairly important places. Sometimes there are changes that aren't worth the commit message, but there still needs to be a commit or maybe there's a commit that you needed for development. That doesn't need to be pushed up or merged right? So you don't have to retie a copy paste messages. There's a command to merge commits and we can sweep that typo or whip under the rug know Juanita needs to know whatever happened. So you had trouble with rebase
in the past? That's okay. We don't need to really grasp 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. So no, none of that. This allows us a lot of flexibility in manipulating the commit history and it's done by opening a text file in your chosen editor more on that in a minute. So this is the file that comes up it's going to serve as a set of instructions to get on how it should handle each commit. We see they're listed out in order oldest to newest. First of the action that we won't get to
take for each commit defaulting to pick second is the short form of the hash that acts as an ID for that commit and finally the subject line of the commit message. Note here that the body of the messages are not displayed just a subject for now. So another reason why I descriptive subject line is important because try messing around to the get history with a bunch of subject lines like some changes to model. And hopefully the available actions we can use are listed below in the comment about portion. I've kind of liking some of them out because today we're going to cover just those four.
Persepolis pick it's the default action for each commit in the basically means use this come it doesn't do anything replayed into the history. Just the way it is. Next up is reword. So use the commit but edit the commit message. Let's take a look at what a real word action looks like in practice. So before we start let's take a look at the commits that we want to change. It's the last commit relative to where we are now. So we use get log head tilde to mean show me the message on the commit right before at where I am. We don't need to
memorize the content here to understand what happens next two paragraphs. He kind of roughly the shape of it. You'll understand. So let's continue on Will use our get me base Dash to get started. And first step is to change the text on the line of the commits that we want to reword. Then we're going to save and close the file. It will read in those instructions and proceed. Get open the command prompt same as if it was a brand-new commit but pre-populated the message that currently exists. We're going to make a really
obvious change here. So what's going on? Play we didn't change the subject line there, but we could if we wanted to and let's log out the same message and see what it looks like now. Call James. I'll superimpose the Old Log and as you can see the commit hash is changed because the content of the commit changed with the message, but the date everything else stays the same. Next is squash. I find it most useful for managing unnecessary commit to creating commits
that more succinctly Encompass the work for a branch because sometimes development needs more commits. Then we're going to need in master. I'm looking at these three commits. It seems like they're kind of doing very similar things and I want to have the messages and changes merged into one commit to push it up for code review. What I want to do is take the commits on lines 3 and 4 and merge them into the commits online to so when you label to commit for squashing, it will be merged into the commit before it. So remember that squashes move up.
because the contents of the commit has changed I want to change the subject to Let's see. A little bit in practice to we'll fire up our Interactive rebase. Same as before, but now we choose squash. save and quit save and quit there. The final that is opened is where we tell get what to do with the messages as three commits become one. Each message is delineate it with a comment. I need section consist of the commit subject a blank line in the message. If we did nothing the new
commit message would look exactly like this. But without the comments. I don't think necessary to me to keep all the outdated subject. So I'll remove their comments to you so I can better see what the finished message is going to look like. And the first line will become our new subjects. And since this doesn't accurately reflect what this committee is changing. We're going to update that too. I'll take a look at the new commits. Now that we're all done. I'm going to use get log - - 1 line to see a compact version of the log with only the
subjects and copy that short hash to use for a get logging will start the printout at the specific commit. There it is. Finally fix up which doesn't really need a whole run through because fix-up merges up just like squash but they commit messages just deleted. This is perfect for typos whitespace commits, things like that. So I could literally spend another hour up here going through get commands and minutiae. So if you wanted more of that I sincerely hope that you went to
Christian music credible Deep dive in to get Workshop yesterday. And as for me, I made a bold promise in the top description that I would teach you how to do all of this get wrangling in an editor other than them. I know this is why you're all here. So I put it at the end. Okay first I do want to show you how to use them just enough to not have to open another application. You can stay in the terminal for all your message crafting needs. I'd get them it will likely drop you into Venom. Yes, and that can be a scary place. If you don't know all of the Arcane
incantations required, but you can handle committing and message editing with three commands. Nothing works the way you're used to when you first get into Vim. That's because you're in a mode for navigating the text not editing to edit. You must enter insert mode, press I to get into insert mode. Then you can type and move around the way that you're used to even the arrow keys work here. When you're done editing you'll need to press Escape. I don't have a mnemonic for that. It's Escape you cancel out of insert mode by pressing
escape. The complete the process you'll type colon WQ colon to enter a command W to write and Q to quit. So all told that I type your message Escape colon right quick. Do you know them? But if you feel the need to use another editor Al we're going to have to do is open up that get config and add another setting. Core as a heading heading editor equals 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 already have that setup if you use a GUI editor definitely for Adam vs coder Sublime. You only do a pen dash dash wait to the command or it's only going to open a blank file. Or you can just run this command from the command line wants if you don't want to set up a good config. So I am pretty close to out of time, but I want to let you know that I'll be tweeting out a copy of these slides as well as the post about all of the other things that I didn't get to cover because after running my talk to the first time. I realize it's about 2
hours long. And some things just had to go. Things like a a mini review of my opinions on plug-ins for most of the major editors and more useful get commands for reading and managing commit history. I really like him. So I apologize for not being able to get it all together for you to be ready for today. But we were woken up this morning by a call from our doggy day care that they had to rush my little boy here to the vet. He's fine, but it's obviously left me with a less time than I thought. I had so not religious or anything, but hugs a distance for
Hanson, please. So I hope that you have all formed or started to form your own idea of what a good commit message is. I think you'll find that the answer to how do we write good commit messages is different for every team every person every situation. Well still considering its usefulness. I'm going to close with my answer to that a line. That is very quickly becoming my personal catch phrase probably get it tattooed written on my gravestone. Maybe next railsconf will hire skywriter the answer like the answer to most things is with empathy.
Empathy for your teammates empathy for yourself empathy for developers of the future. You might never meet. Someone earlier in the week said something that I absolutely love when I told him about my talk. They called me a commit message archaeologist. Yeah, so I encourage you to be commit message archaeologists not the same time to leave something behind that can be useful for fellow archaeologists. And even if you can't convince everyone else that you work with that commit messages should be more than if you're one
in a team of 5 than 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 to and once your message save someone else I'm willing to bet. It'll be a 40% chance soon after so I'll leave you with that thought and a paraphrase quote. Thank you.
Buy this talk
Access to all the recordings of the event
Buy this video
With ConferenceCast.tv, you get access to our library of the world's best conference talks.