Search
Talks
Git is about communication
Edit
Summarized using AI

Git is about communication

Tom de Bruijn • August 21, 2020 • online

The video titled "Git is about communication" features Tom de Bruijn, a developer at AppSignal, who discusses the importance of effective communication in using Git. De Bruijn emphasizes that Git is not just a tool for version control but a medium through which developers relay important information to their future selves, team members, and even potential future colleagues. He shares insights on how detrimental commit messages can lead to confusion and increased debugging difficulty, advocating for a more thoughtful approach to writing commits. Key points include:

  • Understanding Git as Communication: De Bruijn frames Git as a communication tool that facilitates the sharing and understanding of code among team members. Effective commits convey why changes were made, not just what changes were implemented.

  • Consequences of Poor Commit Messages: He highlights scenarios where vague commit messages, such as "fix bug" or "move methods," lead developers to struggle with understanding the context of changes later on, often leading to assumptions that can result in bugs.

  • Improving Commit Quality: De Bruijn encourages developers to make better commits by utilizing multi-line commit messages that include detailed explanations and context about the changes being made. This helps clarify intentions and decision-making processes, providing better historical context for future reference.

  • Documentation through Commits: The talk emphasizes that commits can serve as documentation for the project, allowing developers to maintain a clearer understanding of past decisions and the rationale behind changes. This serves both future developers and the original author of the changes.

  • The Importance of Review Context: During code reviews, sufficient context must be provided to facilitate understanding and facilitate better decision-making and feedback, reducing the need for the reviewer to seek clarifications from the author.

  • Utilizing Best Practices: The video concludes with practical tips such as keeping commits focused, using descriptive messages, and cleaning up history through interactive rebase techniques to create a more readable git history.

Git is about communication
Tom de Bruijn • August 21, 2020 • online

Git is about talking to your team. It’s about talking to yourself, from the future. What about that colleague who hasn’t even joined the team yet? Yes, them too. But how to be "good at Git"?

Tom de Bruijn is a developer at AppSignal, writing in Ruby, Rust, Elixir and JavaScript. Tom writes novels in his free time, which he'll probably publish... one day. Tom helps organize the monthly Amsterdam Ruby meetup, Rails Girls Netherlands events, and previously the EuRuKo 2019 Rotterdam conference.

Welcome to the #NoRuKo conference. A virtual unconference organized by Stichting Ruby NL.

#NoRuKo playlist with all talks and panels: https://www.youtube.com/playlist?list=PL9_A7olkztLlmJIAc567KQgKcMi7-qnjg

Recorded 21th of August, 2020.
NoRuKo website: https://noruko.org/
Stichting Ruby NL website: https://rubynl.org/

NoRuKo 2020

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!
Tom de Bruijn
@tombruijn
Explore all talks recorded at NoRuKo 2020
+10