Hello and welcome to another episode of The Bike Shed, a weekly podcast from your friends at ThoughtBot about developing great software. I'm Stephanie Min. And I'm Joelle Kinville. And together we're here to share a bit of what we've learned along the way. So Joelle, what's new in our world? It is currently, as of the time of this recording, once again, conference call for proposals season. RubyConf has put out their call for proposals. It's currently running until July 22nd.
And we've been working internally at ThoughtBot to put together some proposals from a few members of our team. I also got a chance to be on the RubyConf CFP coaching event as a panelist. They had a few different meetings where people just show up and ask about their fears and concerns or ask for advice on how to put together a compelling top proposal. And out of those two experiences, I came up with a list of questions that I'd asked all these people to try to help them refine maybe a vague idea that they had into something that would feel compelling when put together on a... CFP. And in particular, sometimes you have like a vague idea of like, oh, I'd like to talk about this particular aspect of Ruby. So for example, I'm toying around with something related to randomness in Ruby and how does Ruby's pseudo random generator work. But you have this idea and then you're faced with a empty box and you hit writer's block. What do you put in there? So what I did is I took all these questions I asked and made it into a rubric and you fill those out and there's about 10 questions. And once you've answered them, you have a lot of more fleshed out ideas about your talk and you can then convert that into a pitch or abstract that's much more compelling.
Cool. Yeah, I love a good template rubric situation. What are some of the questions that are on there? So one of the big ones is, who is your audience? Who are you speaking to? And you can't say everyone, because a talk that's named everyone is going to be boring. So in all these, they start with a big question, but there's a little bit of text that goes with it that helps you to think about the question a little bit more deeply. So not just who is your audience, but let's think a little bit about motivation. Why would someone want to come to your talk? What is it that you're trying to accomplish with this particular audience? Are people coming to your talk, maybe intermediate developers who are looking to level up beyond just...
shipping features and want to take on a greater scope of responsibility, and you're going to teach something related to that. Now, all of a sudden, you've got a very specific audience, a target motivation, and you can tailor your talk about how you're going to fulfill that motivation. And just with that, all of a sudden, your talk about randomness can become much more focused. It has a purpose in a way that will make it more interesting to the audience itself and more compelling to the committee when they review it. Yeah, I think that's a great question. And I think it even might be a little bit implicit on the CFP form. I don't know if it's always super obvious that that is such a key aspect of...
kind of pitching a compelling proposal. There's another question that I ask myself or I ask other people when they're kind of sharing ideas with me that is similar. And it's one that I learned from journalism school, the idea of like having an angle on your topic. So I almost think that they go hand in hand about like who's your audience because usually the angle is like, okay, like you said, I don't want to just talk about randomness in Ruby, but like what about randomness, right? And in some ways, once you determine that angle part, I think it almost makes it easier to say like to find who your audience is because that helps you.
kind of, like you said, like something that's interesting to everyone can actually be boring. And so it's like, what is interesting and for whom is it interesting for is a really good exercise, I think. I love that. What's your angle? I should probably add that to the rubric. There's another similar question on there around what is the approach you want to use to communicate this? So some examples might be, this is going to be a walkthrough, a show and tell, or maybe it's a how-to, or maybe it's a, you're teaching a topic. Each of those in the, this is not an exclusive list, there are more, it's going to result in a totally different talk.
So if I'm talking about randomness and I'm doing a sort of a show and tell, I might show you the really cool ways I can just sort of push Ruby's random generators sort of to the max and all you can accomplish with that. And maybe I'm aiming to sort of inspire you. And that's going to be totally different from a talk where I'm like, hey, I'm going to sit you down and you're going to like step by step understand how to work with random generators such that come Monday when you go back to your day job, you feel more capable of using them in your day to day work versus maybe even like, hey. Let's talk a little bit about some theory around randomness. Let's think about what does it mean to be a pseudo random generator? And how is that different than randomness? What are seeds? Why do those matter? Because it's a more teaching topic doesn't mean it can't be practical. You can ground it in practical stuff and then make connections. All right, now that you know these facts about randomness, let's see how they apply. But it's a totally different style of talk. So just with one idea, you can spin it three or four different ways. And that's kind of like your angle idea. I ended up with three different talks. Yeah, yeah, absolutely. And another one that you didn't mention.
that I see a lot, and I think you've done before too, is telling a story. And it could be a story about your experience. Like you actually went through a journey and you tell the story of that. Or it could be like a hypothetical story, right? Or the story about someone else. That's always really engaging. And I actually think, I'm not sure if this is part of your rubric, but another one of the things that I think makes a really strong proposal is when you're able to make a good case for why you should give that talk. And in some ways, I think nailing down what approach you want to do also is really good.
It's also really good information to provide in the like why you, right? Like I am a really strong storyteller or like I am known for being able to like teach concepts, like technical concepts to like a broader audience or something like that. So I've always found that part to be like difficult for some people to fill out sometimes. They're like, oh, well, I don't know. Like, I guess this is just a topic that interests me, which is a great reason. And I'm sure that there are other like lenses too that you can look at your pitch and be like, oh yeah, like I'm able to tell a really great story about randomness in Ruby or something like that. Yeah.
And that can feel very intimidating if it's like, oh, what do you bring to the table for this topic? But everybody that's pitching an idea has a pretty vast set of experiences and perspective and lenses and stories that they can bring a topic in a way that can be really compelling. So sort of a little bit of less than that sort of challenging way of like, yeah, why prove to me that you're good enough to be the one to tell this topic? And more of a like, what's the special thing about you that is going to give a twist to this topic that only you could give? Yeah.
And if you're feeling a little self-conscious or just unsure about how to answer that, one trick that I have found works really well is ask a friend or coworker. And they almost always are able to see things about you that make you special that you might not immediately recognize. And I have done that for other people. I'm like, oh, this is a really awesome way that your past experience makes it so that you have a really unique perspective on this topic. Yeah, so that's my tip for folks out there. I love that. I've published this rubric as a blog post on the ThoughtBot blog.
We will link it in the show notes. So for any of you that are listening to this, maybe before the submission deadline and who would like to try to use it for their conference talk, or maybe you're listening to this in the far future and considering a totally different call for proposals. This is not specific to RubyConf. Check out that link. And hopefully that helps you write a talk that feels more compelling. So we've been talking a lot about conference stuff. Stephanie, what's been new in your world? Yeah, I've been trying to introduce some more boundaries into my work life again. I feel like I fell off the train a little bit in terms of kind of shutting down my work at the time that I say I will. And I can't remember.
It was a while ago now that I talked about how I had this little ritual of taking off my thinking cap, closing my laptop and saying like, schedule shut down complete. I remember that. Yeah. Unfortunately, every now and then I would just remember something that I had to do for work after I had done that. And I was like, oh, but I don't want to forget. So then I would open my computer again and just like throw a note down somewhere. But then I also was finding.
Oh, maybe I'd missed some Slack messages since I had closed my computer. And then I'd go, look at those. It's just dangerous. It's just very dangerous. Yeah, it was really sucking me in to kind of getting back into work stuff. So I'm trying the strategy of like really enforcing, like bookending my work days by at the end of my day, I'll like close all of my windows and close. I'll even like just I'll shut down all of my local development stuff, too, and just have a totally fresh desktop.
And then that actually really helps me in the morning too, because then I'm not immediately like, oh, I have to, I see all these unread notifications and just start digging into that. I open my computer. It's a blank screen. I open my daily note in Obsidian. That's also kind of a new thing that I've been trying. Maybe I'll check what to do I left for myself the day before. And then, I don't know, just kind of plan my day a little bit better than just jumping in. It's more like instead of reacting to things that I missed, being like, okay, here are the things that I need to do. And then when I'm ready to check back in to kind of any messages or emails or whatever.
It's like a choice rather than those messages calling me from my unreads. I love that. The act of consciously shutting down Slack so that if you do have to open that laptop and maybe you do need to check your notes, that red notification badge is not there to pull you in. Yeah. I think it's been very helpful for me lately. So we'll see if I can keep it up. I like that you're not just trying to double down on self-discipline. I think, and this might be sort of the developer in me, but I don't like relying on discipline as the main way to get things done in a way that I want because there's always going to be days where it breaks down.
can I put other systems in place that sort of take that burden away from me? And I feel that about things like code. Like I'll use a code linter because I don't want to just rely on self-discipline to write code in a certain style. So the fact that you're like, hey, what if I didn't just grit my teeth and say, whenever I open my laptop and I see that like bouncing slack icon, I will not tab to it. You know what, what if I shut it down at the end of the day? Yeah, I don't think I'm that disciplined too. So just knowing that it wouldn't work for me, right? And being like, I need to make this as easy as possible for myself. Like I'm not trying to make things harder.
Yeah, so I recommend it if you are in a similar boat of kind of being overwhelmed with notifications when you start your day. We did an episode several months back on making the right thing easy. We were talking about it more in the context of development and trying to make best practices sort of the default thing that your team does rather than something you have to really push for. And this kind of feels like you've taken this idea but personalized it. Yeah, I like that. I mean, making my life easier is kind of just how I want to be operating at all times.
On the topic of discipline, today you and I are going to chat about our Git and GitHub workflows. And I feel like this is one of those things where discipline can kind of be involved in terms of like how you approach making commits and your commit history and your workflow and stuff like that. So I'm excited to get into this and hear just how you do it, maybe how we do it differently. It's like one of those really personal things, I think, that, yeah, I'm sure there's like a million ways to do it. And I'm curious if we have different strategies here.
This is one that can be really controversial because there are like very strong opinions. It is kind of a personal thing, but it also is a thing that you often want to homogenize project-wide. Right. So one approach kind of needs to win out on a particular project, which means that somebody on the team ends up enforcing their style on everybody else. And so sometimes leads to big conversations at work with the team. Yeah. And also the way that you kind of commit or manage your commit history, I do think also impacts others in how they review it. That's like a possibility in terms of expanding scope beyond just like personal preference, right?
So yeah, Joel, do you want to go first about talking about just your workflow? Yeah. So my workflow is to try to chunk my different pieces of work that I do in pretty small pieces. In particular, I will try to separate things that are refactors, things that are maybe enabling some feature work, but themselves do not change any of the behavior. I'm just kind of reshuffling code around to make interfaces easier to work with. And then actual features, and then maybe cleanup work or things like that. So I will try to separate those into separate commits. I also tend to try to break down features into really small chunks, such that...
Each feature can be broken down into little pieces that I can commit independently. I've kind of pushed the how small can I go on my commits. And my lower boundary is basically, I have two rules for something that counts as a commit that I'm willing to ship. And that is, it needs to be green on CI. It can't be broken code. And it needs to be sort of deployable to production. And also, it can't be dead code. So no just like commit that's like introducing new models, like 10 new models to the database. But nothing else. There's no controllers, no views.
Instead, I'll try to do a sort of like vertical slice where I'm like, what is the tiniest little bit of extra behavior that's user facing I can add? It'll cut through all slices, a little bit of UI, a little bit of controller, there's a database, ship that. Yeah, I like that no dead code personal rule. It's that one's hard. I think you have a blog post on this, right? Is it just the working iteratively one? Yes, the working, I forget if it is iteratively or incrementally. But yeah, I talk about a bunch of different strategies. I find it's really valuable to try to break my work into small chunks. So I talk about a bunch of different strategies I have there. Something that I think is an important distinction that I know not everyone has is that
I distinguish between pull requests on GitHub and commits in the Git history. So, and this is where maybe we're going to get into some controversy. My commits are small and atomic and green and independently deployable, independently rollbackable. My pull requests are not sort of units of deployable code. They are groups of commits that I want review on. Oh. Depending on the size of my commits and how related they are, I might do one commit per pull request. But maybe I've got commits that are really small and they are kind of all related and it might be easier for the reviewer to look at them all at once.
And so I might do two or three commits together on a pull request and then merge those all. Where things get controversial, I think, is then like, what do you do with a pull request? Do you rebase? Do you squash? That kind of thing. Okay, there's a lot of things for me to react to here. Do you mind if I share a little bit of my workflow kind of before or up to the pull request stage to kind of compare and contrast and then we can talk about what happens after later? Yeah, tell me a little bit about your workflow and we can then contrast them. So I remember reading that.
working iteratively or working incrementally blog posts a few years ago and being really inspired to do something similar. And I have really gotten better at it, but I think I have evolved to the point where the goal for me isn't always every commit must be deployable and pass CI. And actually, I'd be curious to hear if you do this differently, but I almost consider my local commits my personal space. So I'm okay with making work-in-progress commits before I push to remote. So that works well for me because I find that...
to get into the flow of things, to just be making progress, having to... I'm not running the full test suite, but I am running the tests for the future I'm working on. And I'm also not linting in between each of my commits. I find it easier to do that all at the very end. So in that way, if I were to push them, those commits would not be green because I usually have linting errors. Maybe one day I'll be able to write code that has no linting errors in one go. And sometimes when I am, I get that green linting checkmark. I'm really impressed with myself. I'll pat myself on the back a little bit.
Yeah, I am very disciplined about anything on remote is ready for review in the sense that it's linted, it is green. I actually use force push a lot because... If it fails CI, I'll just immediately amend and make the fix and then force push again. I don't know if you recall this, but at some point, I think in the past couple of years, GitHub changed their UI so it doesn't show how many times someone has force pushed in the past few minutes. And I was so grateful they did because it used to be really embarrassing that I would force push at least 10 times whenever I caught a little thing I wanted to fix before someone looked at it. So I'm glad that they have collapsed that a bit and it's now not as obvious every time I'm making adjustments there. Yeah, I think I generally keep my commits small and well in half.
but I'm less disciplined about each one being like deployable. It does matter to me that like my end product, the diff and all of that is in a good spot for kind of anything that needs to come afterwards. So you raised a really interesting point, the difference between local work and work on feature branches versus work that is on the main branch that gets deployed. And I actually work in a way that's fairly similar to you in that I don't always have my like perfect commits on my local branch or even on a PR. But by the time I merge, I want the main branch to consist of all these nice little commits that you can sort of look at that ideally have a really good description and then have, they're all green, they can be rolled back, they're atomically deployable, all of that stuff. So the main branch has the nice commits. Feature branches do what you want. Where that can be a little bit dangerous sometimes is you can create these giant commits because you just keep pushing stuff to branches and they're all like in different pieces and none of them works independently. So at the end, you're like, you know what, I'm just gonna squash them all into one commit and merge that.
Sure, that works, but, and it's better than nothing because, you know, the commit as a whole is now independently deployable, but it's massive. Yeah, that's usually a cue for me to consider pulling out a separate PR that needs to maybe, it's work that is like, then facilitates the next set of changes. And I guess that's a bit of a, maybe a secret that isn't super well known, the idea that you don't have to do all right up front. It's okay to have this sort of like big messy blob of code as you're like building up this feature and figuring out things. And then you can go back and...
break it up into several commits. Maybe partway through your feature, you realize, you know what? In order to really make this happen, I need this collaborator to have a slightly different interface. I'm going to need to refactor that. And now you've got to refactor intermixed in with your feature work. You can go back and sort of de-intertwine the two and then make those as two separate commits. Maybe they stay together in the PR because it's small enough. And then you would, let's say, rebase into main to get the two commits separate. Maybe you split them out into two separate PRs because they're big enough where you want review or you might want to ship one independently of the other. I'm excited to talk about this because I'm curious how you go about it.
When it comes to editing commits or editing commit history, are you using just like an interactive rebase? I'll do a variety of things. The sort of quick and dirty way, if I'm trying to like split out a commit or series of commits, maybe I've got 10 different work in progress things and this feature's turned into kind of a mess and I want to split it up. A thing that I'll sometimes do is get reset. And be careful, I'm not doing get reset hard because I'm not trying to clear away everything, but I'm effectively just uncommitting everything back to the main branch such that everything is now just in my working directory. And at that point, I can do a git add dash dash patch and say, okay, I want...
these lines of code, but not these lines, and sort of say, okay, this sort of subset of lines of code I want in one commit. Commit those, maybe even check out to a new branch, push those up, commit, I'm good, open a PR. Go back to the branch, or I'm still on this branch, I can check out a branch off the branch if there's a dependency, or maybe those things are independent, so I can sort of make a branch that's separate. Again, git add dash dash patch, and conditionally add a bunch of things, and do this two or three times for as many different pieces as I want. And now what used to be a big blob of code with 10 different work in progress commits is...
maybe three nicely scoped commits that are all independently deployable past CI. And it can be sort of either combined in one PR or separate PRs and then all run into the main branch. Yes, I love git add dash dash patch. I do the same thing. Another tip that I have is you can also do use the patch option on git reset and git checkout. And sometimes I'll do that if I have just like things that I'm like, I can discard this right now. And I'll just manually add it back into some other point.
Those are also really useful. And I also love when you're in that, when you are adding things by patches, you can also split up files as well, like, or split the changes in a single file. I think they're called hunks. Each block of change is called hunks. And so if the suggested hunk is too much for what you're wanting to add, there's a split option. And so then it'll make it even smaller. And ever since I got good at using that, I think my commit history has gotten a lot more, I don't want to say cleaner exactly, but just like.
More intentional, I guess, like more explicit about what I'm trying to do at each step of the way. And it's nice because it's documentation for others, but also really like myself. And it helps me, I don't know what the, I want to say verbalize, but I'm not verbalizing it. I'm typing it, whatever the verb for that is. But putting it like down on like, this is the process that I'm going through. Then helps me get better at that process. Yeah, that's what I wanted to say. Speaking of documentation, an element that comes with making my commits the sort of main story blocks of my history.
is that I tend to put all of the descriptions of what this does and why in commit messages rather than in GitHub pull request messages. Sometimes I'll copy that into a pull request message and GitHub does that by default if you open a PR for a single commit. But I make sure that the commit itself has all that context so that that way somebody who's doing a git blame on a file doesn't need to go to GitHub, doesn't need to have internet access to be able to understand why a particular change was made. So that way it's just one less hop, it's one less dependency. And it just makes that history more accessible to others and machine readable if you needed to. Yeah, that's a really great tip. I guess I did have one more kind of strategy to follow up on in terms of splitting your commits. Kind of the process that we just described, you can also do in an interactive rebase, which I do kind of frequently if I realize that like, oh, I have a commit that's maybe a little bit big or doing two things. And I can tell, especially if I've in my commit message, like written one clause and then said and, and then does this other thing. So as you're going through the kind of rebase to-do list, you can amend any one.
commit, stop there for editing, and do the git reset to then split that commit into two commits, which is a really fancy trick. So even if you have already committed other things, kind of since then, there is a way to rewrite that history from there. So we've been talking about some less fancy and some pretty fancy git tricks. Git rebase in particular can be really scary for people. What would your advice be for someone who's a little bit newer to the industry, isn't as familiar with git? Would you recommend that they follow a workflow similar to yours? Or maybe if we're thinking at the team level, we've got junior developers coming onto our team. Do we want to mandate for the team that they follow a process similar to what we've been describing here?
That's so hard to answer because I don't like mandating anything, first of all. And I think part of why my process had to evolve this way is because I felt the pain and like went through the experience of kind of how I had been working previously, which was a little messier, which was just like less precise or less quote unquote disciplined. And it was only then that I'm like, oh, something needs to change. Like, I think I need to learn some new tricks in my toolbox to help me manage. version control, files change, whatever. So I guess my strategy would be not to mandate anything, but then if I see someone struggling with something or if we're pairing and they see that I have some fancy Git tricks up my sleeve, that is a really great time to be like, oh, did you know that you can do this? Did you know that you can fix up your commits? That's another one that I really like is if I want to smoosh two commits together. So yeah, I think my advice would be to pair with other people, see what their processes are, see what kind of neat things they're doing. I think another that reminds me that Git aliases, I think, can be a little bit...
obscure for newer devs where people who are newer to Git, I use them very heavily. And I have a little script in my Zish config that actually prints out the full Git command, even if I'm using an alias. So if I am pairing with someone, they see that like, oh, GAP is my Git add dash dash patch. Oh, that's really fun. Yeah, it's nice because there was a while where I was using some fancy aliases as pairing with someone. They were like, what are you doing? I'm like, oh, you don't know. And especially because aliases are kind of different for everyone. Yeah, so that's something that I think was just like, I did that once. And then since then, I've never had to run into that problem again. Is this published anywhere online?
I don't think it is, but you know what? After this, I will stick it in a little snippet. Yeah, maybe put it in a gist or something. We can put it in the show notes because I'd love to see that. That might be something I need to crib for my own .files. That's a good idea. Thanks. I think it can be really hard to avoid mandating anything in that you don't want to have a junior. Let's say you decide, hey, we're looking to do more atomic commits, and then you have a junior dev who comes in and just dumps 30 whip commits into your main branch. That's going to mess things up a little bit, especially if you're working off of generally an assumption that commits are deployable. I think something that I've found is a bit of a useful middle ground, especially for newer devs who are trying to get into something like this.
is the squash button on GitHub. So you can say, look, you can put 50 whip commits on your branch. And when you're done, you hit that squash button. And that's going to turn into one commit. And you can edit the message so that it's nice and clean. Please do. Don't have it. GitHub will just take all of the messages and append them all in a bulleted list. I'd rather not have a commit on main that is just 50 bulleted lists with the word whip in it. Ideally, it's something a little bit better. But you can do that. And maybe at first, your PRs are pretty big. But I think what I would encourage a newer person to do is maybe not try to go super deep into Git just at first. But instead, learn to scope their PRs a little bit smaller.
And within that, they can do as many sort of whip commits as they want and squash them down. And you get a single commit at the end. And then as they start building experience, they get to be good at scoping their PRs smaller. Then they can maybe start to explore fancier rebase stuff and say, hey, maybe I'll do a PR where I want to not squash it down into one. I'm going to have two atomic commits with it because they're small enough that I want them reviewed together. And then they can be shipped together. Instead of squashing them, I'll do a rebase and merge. That's more advanced. But for more of a beginner, I would suggest squash button is your friend. And focus that sort of first phase of learning on learning to scope your PRs smaller.
Yeah, I like that. I think for the most part, that merge strategy, I've not been in a position to decide like how it should be for the whole team. And I think I've been, I think the trend has been more like to see a squash and merge, at least on client projects that I've been on recently. Have you seen differently? That has been the trend that I've seen. Yes. I know there are vocal proponents of the merge commit sometimes with the idea of like, oh, but what if I want to be able to see the history of the changes? But like I was, this person was on a branch. I want to see their entire like thought process as they were working through it and all 50 sort of working progress commits so that I can see.
step by step where they were trying to go. How do you feel about that? Oh, weird. But only because I am able to do that from the PR page. So in some ways, I think this is where the synergy between Git and GitHub really shines, where it's like, I don't necessarily need to merge it as a merge commit because that history exists somewhere else. But if you're squashing your commits or doing a force push, then it doesn't exist on GitHub either. I'm thinking that the commit message would include the PR number, at least. It will, yes. But if you're squashing the commits on your branch.
or doing force pushes on your branch, then if I navigate to your PR, I won't see all 50 work in progress commits. Oh, okay. Especially if you're doing a local like amend and then push up workflow or something like that. I think what you do maybe get the best of both worlds, if you do the 50 whip commits on your branch, hit the squash button on GitHub, and then that becomes a single commit on main. Then you get on the GitHub PR, you can see all 50 whip commits, but then on the PR, you still get that one nice atomic commit. Okay, I thought that was also true if you did a merge commit strategy on GitHub. Yes, yes, that is true with a merge commit strategy.
Okay. That's what I was thinking. Which is what proponents would say. That's why they would want a merge commit strategy. I see. As opposed to the kind of strategy that we're talking about. I guess it also depends on just how, if those commits were able to be followed to begin with a little bit. If that is how your team works by default, then yeah, I can see at that point you're prioritizing different things. But I find that I would not get very far going through a commit history that wasn't necessarily laid out for me to read in that way. That's a good point. Yeah. I don't think I've ever...
felt the need to like, if I had an atomic commit on main, I don't think I've ever wanted to look at the, oh, I wonder what journey this person went on for this. What does whip commit 25 of 50 look like? That's never been a question I've asked or needed to have answered. And maybe that's been true for other team members who work in a slightly different workflow, but that's not a thing that's been valuable for me. And so I've never felt the need to have that as part of my Git or GitHub workflow.
I will say that there have been times that I have just given up trying to like rebase something. And especially if it's like if I've had a long running feature branch and main has diverged a lot and I'm trying to rebase main into my feature branch and I have to kind of figure out how to resolve conflicts each step of the way. Once I'm getting into the nitty gritty of that, I am actually very poor at like doing tedious things, tedious work like that. And so I might just do a merge. commit there. Actually, there was one time when I joined Chad for a live stream and the first like 30 minutes of it was us trying to do exactly what I just described. And things got so wonky that I think I was like, I think we should just delete our local branch and refresh the remote one to just start completely over. And that is totally fair. Like, I think I even was like, this is what I would do. Like, I've just given up and was nervous about saying that because I was like, is there a way that we can kind of figure out how to make this work? And it was very validating for him when I went in, when he told me like, he's like, yeah, that's what I would do too. So even very experienced developers kind of.
Just recognize that. Sometimes you give up. Sometimes you give up. But that's not like what I reach for normally, right? It's kind of like if my regular processes just aren't working for me right now. I think similarly, and I think part of the reason why that's not often a concern for me is that a long-running feature branch is kind of by definition the opposite of the workflow that I'm talking about. I'm trying to do tightly scoped short feature branches with like one atomic thing. And even for something big, like let's say a Rails upgrade, I've seen the long-running branch approach fail so many times. Instead, find small things that can be incrementally like shipped and merged back into main.
that will lock in those wins, that's a much more effective strategy than over two or three months doing a bunch of changes on a long running branch and trying to keep that up to date with Maine. That's just asking for pain. Yeah, yeah, that's a good point. And maybe that's kind of what I meant earlier too when I was talking about like, you really have to experience it to be like, oh, I should be trying something else. And sometimes it still happens and that's okay. It probably just kind of reinforces for me the idea like, oh yeah, that's why I avoid doing this. You don't have to be dogmatic about it, but you can sort of have this as a North Star. My commits aren't all like perfectly, like super tightly scoped, but...
The trend I try to have is to scope them smaller and smaller, because I find that that helps me with my focus, it helps me with my velocity, and it generally allows things to get shipped a little bit faster, makes it easier to, if there is disagreement with the team on implementation, you can ship some parts and sort of not hold up the entire feature. One aspect that we haven't talked about, and I'd love to get your thoughts on, is PR size. So we can talk about commits and how we like to scope them. And we've mentioned that, at least for me, I sort of decouple the idea of atomic commits from PRs. So sometimes I'll put multiple commits that are atomic on a PR. Sometimes I'll have a PR that has a bunch of WIP commits that are not atomic. But all that can add up to size. Do you have a number where you like to cap size for PRs? Yeah, that's a good question. I find it more useful to think about it in terms of files changed. So I think 10 is a good signal for me. Interesting. Yeah. I haven't thought about this too much, but there is something to the idea of like the more files changed, the harder it is to hold in your head. Like what changes are involved? Agreed. Yeah. So I'm a little less of a stickler on line.
count, but files change seems like a good heuristic for me. Yeah, 10 or less is ideal. That reminds me of the shotgun surgery code smell, where you're having to touch a bunch of different files because the code that deals with a particular feature is just so sort of entangled everywhere in your code. And that can speak to the fact that you've got high coupling and low cohesion, and maybe there's a missing abstraction. I think for myself, I tend to maybe be a little bit more traditional here, gone by lines of code as a heuristic. I usually aim for, and specifically for Rails code bases, to be about 100 lines of code of diff. Different languages are a little bit more or less verbose, so that number can be different.
And it's not a hard and fast rule, but I'm looking to aim at about 100 lines. And if it's more than that, I might ask myself, is there any way that I can scope this down more or split it into two different, at that point, usually features, because I might be doing so much work that maybe this can be two different little chunks of functionality. Yeah, that's a great point. I feel the same way. And there's so many opportunities to clue you into that, kind of what I was saying about when my commit messages start to kind of like have clauses, right? Or sometimes I do...
fall into the trap of adding bullets in my commit messages for all the kind of things that changed in there. And that's usually like a good place for me to evaluate like, oh, are these like, what's the scope of each of these bullets, right? And then that's also true for your PR title or your branch name or whatever. Like, I think there's a lot of opportunities to reevaluate or reassess kind of the scope of what you're trying to do. Oh, can I tell you about one of the most satisfying forms of commit messages that I write? Please. These are commit messages where you've been hunting for a bug and it's like some like really weird thing.
And it ends up being a one-line fix. And then the commit message ends up being like an essay. Yeah. Ooh, that's great. I find that satisfying. Yes, that's really, really helpful. Because like saying in your commit message, just saying like fix, blah, blah, blah, doesn't then like kind of document all that went on to doing that. And sometimes it is a lot, right? It can be even days of work. Especially for those bugs where it takes like days of work. Why this particular line caused the bug is often not evident. It took a lot of other searching to figure out why this particular line was at fault.
And so that's where sort of that essay comes in of like, hey, I ran all these different tests and it turns out that this particular thing combined with this version of the database leads to this particular bug. I know sometimes I might include even like an ASCII diagram or something like that just to sort of show why this particular line changing was the cause of the problem. Yeah, I like that a lot too because it really like showcases the work that you did. It wasn't just the one line change. And if someone was just looking at like how many lines of code you wrote or didn't write, like that doesn't tell the full story. And it's a way that you can kind of...
remember for yourself and also point to later if you need to. Like, hey, like, this is all the work that needed to happen to for this one change. And I don't know, it feels very representative of like, this is what our like actual work today is like. It's not just writing code, right? It's kind of all the things that doesn't happen behind the scenes. And some online changes are almost like really simple. They're almost like dumb changes where you're like fixing a bug and you're like, oh, when I originally wrote this feature, I forgot to call save on my model. Oops, it was broken. I added save. Like that, you don't need an essay to explain that. But the like, oh, well, when...
It's daylight savings in the Eastern time zone. And the video timestamp starts with a four. This like, when converted to microseconds, has a weird behavior in the database. That's going to require a whole essay about why that's happening and why we need to like round to the fourth decimal. And why four in particular, like I want to know. Because the next person's not going to look at that and be like, oh, clearly you need to round to the fourth decimal because of that daylight savings bug. So as we wrap up here, I want to ask you a final question going back to pull requests. And I think we've been talking a lot from the perspective of writing code. But a big part of our job is reviewing code.
So what makes your life easier as a reviewer when you are reviewing a PR? And that can be in terms of like the way the commits are structured, the size of the PR, things like that. What do you like to see as a reviewer? I like being told how I should review it. Oh, that's good. Yeah, and I actually try to do that for other people too. Someone will say, this is best reviewed commit by commit. And I'm like, great, I'm going to do that. I really like when people annotate stuff as a GitHub comment. And I find this, I've talked about this before, I think, but this is different to me than what you would put in a commit message because it's like, this is what I want, like you said, like the audience or like the reviewer to know about.
something I'm doing here, but it's like temporal, right? It's like, it's not meant to be permanent. It's just like, maybe it's something like, oh, like this change corresponds with this other change in the controller and you link those lines changed. I love stuff like that because, you know, sometimes the order of the files changed isn't very conducive for reading the story. And so sometimes like when people leave notes like that, it makes it so much easier for me to follow along if I'm not going commit by commit because sometimes that's just not how the history was written and that's okay. Yeah, that's a great point about sort of the purpose of a PR description. I tend to think of it as, I mean, you might include the commit message in there.
But it's annotating that with extra information that will make the reviewer's life easier. One that I often like to put in my commits is best reviewed with whitespace mode on. So GitHub is a mode where you can ignore whitespace. So if I did a thing where, let's say, I added a namespace around a file. And so everything in that file got indented, but I didn't change any of the content. I don't need you to go line by line with this 100-line file when all I did is wrap a module around it.
So by putting it in white space ignore mode, it will ignore all those lines that didn't change, just got intented. And then the reviewer has a much smaller diff to look at. So yeah, anything that is like specific to the context of like you are on GitHub giving review to this should go in GitHub comments, in the GitHub PR description. Anything that's sort of like eternal to the project, anybody reading this is going to want to know this in the future, goes in the commit message. And just as you can on PRs link other PRs, you can link commits to each other by putting the commit shah in the commit message. And GitHub will auto link those, but you can also in on the command line do a git show.
paste a commit shot and it will show you that commit. So you can say, hey, inspired by previous commit or building on the work of previous commit or reverting previous commit, things like that, where you just put the commit shot. And I found that helpful from time to time. Well, I feel like I wish I could go review some of your code now and just see how. how much and what we talked about today, like how that manifests in your commits and your PRs. I don't think we've really like worked with each other in that way before. So I look forward to the day that I get to do that. And yeah, I hope our listeners learn some cool Git tips and tricks. And we would love to hear if this matches your workflow, if you have any cool strategies for making your life easier. As I said earlier, the motto for me, at least. Yeah, you can write right into us at host.bikeshed.fm. On that note, shall we wrap up? Let's wrap up.
Show notes for this episode can be found at bikeshed.thoughtbot.com. If you enjoyed listening, one really easy way to support the show is to leave us a quick rating or even a review in iTunes. It really helps other folks find the show. If you have any feedback or questions, you can reach us at hosts at bikeshed.fm via email. Thank you so much for listening to The Bike Shed, and we'll see you next week. Bye!