00:00:07.359
Hi everyone, and we're back! I hope you have enjoyed your pizza.
00:00:12.799
I certainly enjoyed mine—a pineapple-less pizza. Before we start our next session with our following speaker, we have another developer dilemma ready for you.
00:00:21.359
You'll find the link to this developer dilemma in the chat. Please pick one: "Every commit goes to production" or "Deploy once every quarter." Jump on in, cast your vote, and meanwhile, we are now welcoming Tom.
00:00:36.880
So, can you tell us a bit about Tom?
00:00:43.680
Absolutely! Thanks a lot! I'm so excited to tell you about our next talk from Tom. Tom here is a published science fiction writer, and he's going to discuss how to use Git and how we communicate with it, as well as how communication ties into the way we use it.
00:01:04.158
Now, I’ve been informed that Tom dreams of one day piloting his very own Gundam machine. For those of you who aren't familiar, Gundam is an anime show where people pilot giant mecha pieces of armor that fly around in space! I'm very excited to hear about this, and without further ado, Tom, the stage is yours.
00:01:22.080
Thanks, Amon! I'm happy to be here today. Yes, we'll be talking about how to buy your first Gundam; that’s a very important topic we need to discuss. Oh, actually, my phone is going off. Well, I have another problem: a bug report has come in, and I saw that the customer was already in our support channel asking, "Is it you, or is it me?" So, maybe we should look at how to debug this issue instead.
00:01:46.079
We can make the customer happy, we can make ourselves happy, everyone will be happy, and we'll have a more stable system. But as I'm looking at the code, it doesn’t really start to make sense to me. I'm asking myself how this was supposed to work in the first place, which is not a great mindset to have when debugging something. I grabbed my trusty tool, called Git, and let's look at how this code works or how it's written.
00:02:22.639
But we're out of luck; we don’t know. We need some more information here.
00:02:29.680
Okay, no, that’s not going to work either. A work in progress in production is no longer in progress, so this isn’t going to be helpful.
00:02:43.680
Strap in, we're going to be here a while. Today, I want to talk about why Git is about communication. I'm Tom, a developer at AppSignal, and I believe communication is essential. Git is a great tool we can use for this.
00:03:10.959
So, how does the situation we just ran into happen? How do we get such bad git blame? We all know that person—the hackerman, the rockstar, the ninja, the 10x engineer. They churn out code. Management loves them. They run through story points and deliver features to customers—it's all amazing.
00:03:30.159
But then we get this kind of commit, and that’s just not helpful. Something stands out when I look at this timestamp, and I begin to wonder, did Dave go to lunch? Maybe his colleagues were already waiting, saying, "Hey, we need to leave if we want to make our reservation.” He might have thought, "Ah, work in progress, back it up, push to GitHub," because last time his laptop crashed and he lost all his progress.
00:04:00.080
So never again! But then he never went back to improve that commit. Git is not simply a way to get your code to production; it’s not 'Command-S' with more steps—it’s so much more.
00:04:34.080
Communication is essential in development because development isn’t just about typing code. We love typing code, but we are also talking to our users, our team, and our product owner. They have all the important information about what we should create and what we should focus on.
00:05:01.039
However, a bad git blame indicates a breakdown in this communication because nothing is being communicated here. But we do use git blame, right? We’ve all run into this situation where we look at our code and—without even using git blame—we just open a file and wonder, "Who wrote this?" Only to find out that it was us.
00:05:21.199
We know the situation, but how can we improve it? Git blame should help us debug; it shouldn’t be another source of frustration. It should provide information and not just cause exasperation. Git is about talking to your team; it’s also about talking to yourself from the future.
00:05:51.759
So tell a story. Tell the information you know now because someone might need it in the future. The source of this problem is bad commits. A code quality measurement is 'wtf per minute' if we only look at the code itself.
00:06:23.440
But if we find ourselves in a situation where we run out of knowledge or information to figure out why the code works the way it does, we look at git blame and it's yet another source of confusion. It just piles on bad code quality measurement, and I must admit, I'm definitely guilty of writing many bad commits myself.
00:06:59.679
For example, looking at a commit from 2017, I'm like, "Great, Tom, why did you do that? What changed?" I have to look at the diff to understand my cryptic and incomplete message about what I was trying to do. I have a little personal hall of shame here.
00:07:32.560
We all know the work-in-progress commits. It’s abbreviated because we're in a hurry, and we just want to ship the new feature. But we also know the 'fix bug' commit: "I'm going to fix a bug... which one? Figure it out!" And then, of course, I need to update the test because while fixing that bug, I broke a whole lot of things.
00:08:06.240
Lastly, I dislike the commit message 'move methods.' Why did I move it? Was it more aesthetically pleasing in another location? Who knows? I can't tell from the commit message anymore! Or this one just says 'closes something'—an issue that leaves me in the dark regarding whether it was a bug, a performance issue, or a new feature.
00:08:56.000
Can't tell anymore because we used GitHub in the past and we use Jira now, and we no longer have the information in GitHub, so that is just lost in time. My least favorite one is the 'three dots' message. It's just not a continuation of this list; it’s three dots!
00:09:31.239
Those commits all start to blur together. I’ve worked under someone who committed work like this, and it was not fun. So what do all these commits have in common? They're unhelpful; they don't communicate anything and don't tell us why this change was made.
00:09:53.600
The problem is that I have to make assumptions, which can lead to more bugs. I’m unaware of what I need to consider, and I could break some obscure part of the system that I've never worked with, but relies on this code. You might think to yourself, "Well, I can just ask the author, right? They might still know why they wrote the code that way.” But that’s not often the case.
00:10:27.679
They might be sick, on vacation, or have left the company entirely. Even if they are available, it might be 3 AM when a critical bug has appeared, and you’ll have to wake them up to get that information. So, if there's any time-sensitive information you need, this is not a great way to handle it.
00:11:07.600
So how are we going to fix this bug now? We ran into bad git blame and we're out of luck. We need to figure out what to do next. I start a Slack call, Zoom call, or whatever you use, and I invite my team members. They might have worked with this person, Dave, or have touched the code more recently than I have.
00:11:41.760
But I do have to stop them from what they're doing to pull them away from their work to help me with this problem. But did we figure it out in the end? Awesome! Celebration time! We fixed this bug! But what do we do next? Just git commit fix bug, right?
00:12:18.080
And then we just move on. I have another list of bug reports that have come in; I need to address those, or that feature has been delayed by all this. No, we shouldn't make the same mistake again because three months from now, we could end up in the same situation.
00:12:52.960
So how do we prevent this from happening again? We make better commits. If we just look at the simple command of adding a commit—like fixing a bug—I have a big pro tip to make your commits a hundred or even a thousand times more useful: Git commit supports multi-line commits!
00:13:30.160
You don’t have to cram everything into the first sentence or the subject line; if you just run git commit without the option, it will open your favorite editor. In my case, that's Vim where I can start typing my subject, then add a new line for a paragraph in the description, and just continue to add everything I want. Nothing is going to stop me there.
00:14:09.600
But what do we actually write? I have a format for that, and we’ll get back to that in a minute. But first, let’s discuss something else I find important: commits are part of the project documentation. We have a lot of other different sources for documentation.
00:14:45.760
Most projects have a README; maybe there’s a wiki with some more advanced guides. You might encounter a bug on this system; there may be a guide for that, but good luck with inline comments—no one updates those, and they’re going to be outdated.
00:15:27.679
As developers, we often find that writing documentation isn't fun. We want to ship features or fix bugs instead of writing all the things we thought about while making changes. But without documentation, we might find ourselves back in that confusing situation.
00:15:56.960
When we write documentation, we need to consider that it's for the people who aren’t there—not just for future us, but for team members or even external users. This can be like physical meeting rooms where if anyone missed a particular discussion, they need to know what's going on.
00:16:34.559
Anyone can write this—it’s not rocket science! You can start small and build your way up. You don't have to write a giant novel from the start, but we do want to aim towards that.
00:17:18.799
Next, when we look at our commits, we should review pull requests. We get assigned a progress request, then we put on our reviewer hat and determine what constitutes a good review.
00:17:54.720
How do I ensure the author is satisfied with my review and that it serves its purpose? However, if I open a pull request, and it’s long with everything blurred together, I just want to approve it and move on, but that renders the review worthless because I haven’t really examined the details of the code.
00:18:34.560
What can I do to make this better? One thing I do is check out the code locally and just start poking around to try and break it. Does the test actually do what it’s supposed to? But the issue is I'm testing code quality without knowing what it’s actually doing.
00:19:15.440
How do we know what the change should actually do? If it just says 'fix bug,' I want to know what bug it fixed. As a reviewer, I can start asking questions: "What error did you encounter here? Why was this slow?" For in-depth reviews, I should gain more knowledge about the problem.
00:19:38.880
The issue is that I need to ask the author and they have moved on. They could be starting on a new feature or bug and need to stop what they were doing to explain to me why they did things a certain way, which can take time.
00:20:15.120
This can take an hour, two hours, or even a few days, then I have to re-read everything when they explain it to me, which is a time-consuming process that shouldn't be necessary if information was provided from the start.
00:20:54.679
So how can we improve this? When you send in a pull request for review, ensure the reviewers have enough context to review it properly. They need to know what bug is being fixed, and all that stuff so they can leave a more critical review.
00:21:40.120
How do we provide this context? Explain the why—why did all of this happen? I've probably used the word 'why' a hundred times because it’s crucial. This explains the commit’s context.
00:22:22.319
We shouldn't be making assumptions. Git blame is actually terrible terminology since I’m not looking to blame anyone. I want to know why this change was made. I'm not going to assign the bug to the original author of the line where the bug occurred; that isn't helpful.
00:23:05.440
Instead, if I get assigned this issue, I'm going to fix it. You can alias the git blame command to something more positive, such as git why.
00:24:03.360
We must write down why the change was made, not just what was changed. I can check the diff to see what was modified, but I think the main point of my presentation is that we must write down why the change was made.
00:24:52.600
For example, I start off with the scenario like what brought me to this moment—not just when I got to work. Instead, I would write, "This bug occurred; this incident was reported in the error tracker." I don't just link to the ticket or the issue, since systems change and that ticket might not exist years from now.
00:25:31.599
I need to write down why this is happening and why I made the change. Templates that I can use are like, "When something happened," or, "This error occurred," or, "One morning I woke up and thought, yes, I know how to refactor this ugly class I’ve been screaming at for months. I know how to make it look better.'
00:26:18.880
Then I can explain how I solved the problem, and the git diff will help there. It tells us what changed but not why this particular line changed in that way.'
00:27:05.600
It’s crucial to explain in the commit why this solution was chosen specifically. This can be as simple as saying, "I forgot to initialize the class before calling the method." However, usually, it's a bit more complicated.
00:27:39.440
I then outline the alternatives, as these give vital context to the commit. Why did I choose this particular solution? There could be ten other ways to do it, but I decided to go this route.
00:28:06.599
If I write down which ones I considered, my teammates will know if I missed a better solution or if a technical limitation prevented me from implementing a different approach. That kind of information is valuable and prevents someone from struggling with the same problem months later.
00:28:51.680
My favorite reason to document thoroughly in commits is to prevent annoying questions during a review. Nothing is more frustrating than going through the process of finding the best solution and then seeing someone in a review ask, "Did you consider this other way?" Yes, I did—but explaining it again loses that valuable information.
00:29:32.800
Template language to use could be phrasing like, "I considered something, but couldn't do it," or, "I wanted to do something else, but I settled on this solution instead." If you found an awesome blog post that resolved your problem, link to it, but also copy and paste the important content into the git commit because that blog post might not be around in the future.
00:30:07.120
Finally, the subject. I probably started off with a subject that wasn’t the best, but now that I've internalized this entire process—why I made this change, how I did, what alternatives I considered—I can write a much better subject for my commit.
00:30:54.960
If all goes well, we start with a work-in-progress commit, but eventually, we move to something like this: the more information the better. Just start writing; put as much context into the commit as possible.
00:31:27.600
How do we make pull requests easier to review? If I have a branch with just one commit, GitHub helps a lot because it pre-fills everything for me. It adds the title as the subject and all the commit content as the description. I just need to press create and assign some team members to review it.
00:32:14.880
But if I have multiple commits in this branch and don’t want to split it up, GitHub doesn't pre-fill it for me. So, I copy and paste all the commit messages and subjects into the description, add headings to differentiate between the commits, and all that information is right there at the top.
00:32:58.000
When someone opens the pull request, they see all the information and can start reading before switching to the changes tab to check if my code quality is adequate.
00:33:38.560
My rule is that pull requests should only contain the content from the commits. If I add any new information specific to that pull request, it’s lost in the future. The one exception might be a cool screenshot or two of a new feature with design—all of that can be included in the description.
00:34:23.120
Another way to make reviewing easier is by making smaller increments. If I need to decide between a pull request with many changes versus one with fewer, I know which one I'm going to choose. The first one has too much going on; I can’t scroll through it!
00:35:06.560
If I look at a smaller pull request, it's usually one change with one type of context I need to consider. I don't have to navigate through the whole project to understand this particular fix.
00:35:47.040
My biggest annoyance is encountering a messy git history. Too often, I see a history cluttered with commits that just leave me confused. I just can't comprehend what's happening here.
00:36:21.760
So, please start creating a tidy history. If we start off with a 'work in progress' commit, I look for more substance in future commits so that what’s actually under review isn’t confusing. If something starts blurring together or shows unnecessary merges, I’m likely going to reject it.
00:37:10.080
How do we tidy things up? We can use the Git rebase command, which is not as scary as it sounds if we use it interactively. Choose the base branch to branch off. Start with the WIP commit and merge everything else seamlessly.
00:37:40.640
We will first refactor, and then add the new feature and test fixes into their respective commits as they belong. If done correctly, we can end up with a cleaner history.
00:38:05.680
What did we learn today? We do this for our team, but also for our future selves. We try to communicate better through pull requests and git blames, and all the information we add now can serve us well in the future.
00:38:47.920
The best motivation ever is to just make things easier for yourself. If you do this, it will become so much easier for you in the long run.
00:39:26.240
In summary, commits should explain why the change was made, as well as why this particular implementation was chosen. If you considered alternatives, write them down and explain why this solution was better.
00:40:01.080
Make small pull requests so they are easier to review and create a tidy history. This makes reviewing simpler and leads to better reviews because people will know what they are reviewing and why changes were necessary.
00:40:38.080
Our paths will cross in the future, and if a bug slips in down the line, the information we provide now will help resolve any issues faster.
00:41:04.000
Your future selves, your team members, and even colleagues who haven’t joined yet will thank you for taking the time to document that information. You've saved them from having to figure it out all over again.
00:41:43.680
If you’re interested in this topic, I wrote a blog post before giving this talk about the same subject. Feel free to read it if you want more information or just want to reflect instead of watching a talk. If you have any questions, now is the time. Thank you all for listening!
00:42:21.200
I'll wait for my MCs.
00:43:11.240
Tom, that was wonderful; thank you so much. I solemnly swear I'm never going to write a commit with three dots in it again.
00:43:32.080
Okay folks, let’s take a moment. Give Tom a chance to grab a drink. Meanwhile, I would like to share with you the results of our third developer dilemma: deploy once a quarter versus every commit going into production.
00:43:59.520
And the results are in: 18% said deploy once every quarter, while 82% said every commit goes to production!
00:44:45.720
With that said, Tom, I would love to ask you a couple of questions.
00:45:05.840
My first being, how do you feel about semantic commits?
00:45:23.280
I don’t know if you're still there, Tom. Let me move you onto the screen so I can see you. There you go!
00:45:49.200
Alright, semantic commits—yes, I'm not a big fan myself. I know the prefixes for all the commits describe chores, features, and documentation. I don't think they add as much value as they should.
00:46:42.760
I think another speaker here wrote a blog post specifically about semantic and conventional commits, and why it’s not the best practice; it draws parallels to just linking to GitHub or Jira tickets for explaining why a commit is made. I believe we need to add much more information than that. I need the characters at the beginning of the subject line to explain what the actual change is about.
00:47:35.840
Thank you! On the note of characters, here's perhaps a contentious question: What are your thoughts on emojis in commits?
00:48:10.160
No emojis in commit subjects. I know at AppSignal, we tried this for issues and commits, but ultimately we dropped it; it wasn’t as useful as we hoped.
00:48:31.760
How about is there such a thing as a commit message that’s perhaps too long?
00:48:53.640
Well, if you have to read it, sure. But if you're in that position, you probably have a lot going on, and you want all that information. If the author tries to shorten it for readability, they may leave something out.
00:49:03.760
That's a good point! Alright, I think we have time for one or two more questions. Here’s one from me: The impression I've gotten is that writing effective commits is a skill. How long do you feel it took you to reach a point where you’re proficient at it?
00:49:43.840
I looked yesterday at what I think was my first commit that included a subject. When looking at AppSignal code from 2012 or 2011, I made many commits with no description. But in 2012, I fixed a bug and added more details because I realized something I was doing was very weird that wasn’t conveyed through the diff itself.
00:50:18.800
Since then, I’ve been spending a lot of time improving my commit messages. I don’t think it took eight years to improve. Rather, I think two to three years is a good timeframe to really get into that mode of knowing what is important to document.
00:51:09.440
Thank you! To follow up on that question, do you think our needs in terms of how commits look will change in the near or distant future? Would you say you’ve reached the end goal of a good commit message?
00:51:58.160
If we follow the steps I just described, then yes. Of course, we can always improve upon it, but for now, doing this would certainly enhance the process.
00:52:36.160
Excellent! Well, I think that's all I have. Thanks for tuning in and a massive thank you to Tom for your incredible talk!
00:52:54.160
We’re heading into a break before Alison's talk, but don't touch that dial— we’ll be right back!
