Hasty Treat - Writing Good Commit Messages

Welcome to Syntax. In this Monday, hasty treat, we're gonna be talking all about conventional commits.

And if that sounds like something you never heard of before, then you are gonna be very excited about this one because this is gonna be talking about commit messages and a system for The sort of specific commit messages that you can write that can then have more intent and functionality within your application overall.

Commit messages are hard, and having a system for it takes all the guesswork out of it. So we're gonna be talking about conventional commits in this episode. My name is Scott Talinski, I am a developer from Denver, Colorado. And with me as always is Wes Boss.

Hey. Hey, Wes. You know one place where conventional Well, commits will definitely come in handy is your Sentry because you can get what commit, what version everything happens to if you connect your Repo to century at century.i0, which is our favorite error and exception handling tool that allows you to track all of the exceptions and errors in your location. In fact, you'll wanna check out century at century.i0.

Use the coupon code tasty treat, all lowercase, all one word for 2 months for free.

And, again, one of the cool things here is that when we're dealing with conventional commits, right, we can attach specific commits To our code in century or specific versions. You can see which version and what kind of commits went into this code. And it's so nice that you'll be able to track all of this and say, hey. Remember that thing that you did? There was an error there. And then in your commit message, you can, actually Have a better idea of the bug that it fixed or anything like that that you're attaching because maybe you're creating an issue automatically in GitHub in Sentry, And then you're referencing that issue in your conventional commit. A lot of cool stuff here. So let's get into conventional commits, Wes. Is this something you are currently using?

No. It's it's not. Like, we mentioned a couple episodes ago that, like, pretty look. Pretty good. I can use them. Sometimes we put garbage ones in there. I don't I don't put And that's fine because Speak for yourself. Because you can squash them all into into 1 commit. But I've been seeing a lot of poll requests come in lately with something like Build colon or fix colon or chore colon or refactor colon, and I I'm like, oh, that's cool. But then I see it over and over. I'm like, There must be something that people are following, and I found it. It's conventional commits. And this is really interesting to me because, a, yes, it does give you much better history as to what happen, but what I was surprised to find out is there's lots of tooling around parsing these commits and helping you decide what to release or what changed. And That's really interesting because, like, I've been working with the folks on Keystone lately, and every time that they put in a commit, They also commit a dot change file, and it will describe what changed. And then when they do a release, they're able to just automatically compile all of those What changed? And they have all these like, you know, you you look at the the change releases as to what happened. I was like, oh, that's how people are generating these things. They're automatically doing it. They're not just someone Been like, what did we do since the last Writing him a bunch of Yeah. Right. You know? On on what specific commits do those changes happen? Yeah. I thought that was really cool, And I'm assuming that's what Versus Code does as well because every time Versus Code releases, they will link back to a commit that actually happens. So so what is it? Well, Every time you have a commit, in your commit message, you will write the type of commit. That can be fix, feature, breaking change, build, Chore, refactor, test, perf, colon, and then you write a description of of what you changed. And then there is In optional so commit messages can be multiline.

You can have an optional body, which describes it a little bit more, and then you have optional footers, Which is often used for custom stuff. Like, if you want to if you run Jira and you wanna link it back to a Jira tag, You could put the Jira. If if you have a specific reviewer, you wanna, like, link up who reviewed something. You could put their name in there, and you could automatically parse those out into it. So it's sort of like a syntax format for code changes that is also readable. I would say it's a a conventional

it's a convention for writing commits.

Is that Yeah. That's what it is. Yes. You nailed it. You should register that domain. Yeah. So neither of us Wes and I haven't Haven't necessarily started using this yet, but we're both gonna give it a a good try. Right? And I think we may we should do a check-in and and talk a little bit about what we've learned about conventional commits Over time.

So you mentioned that there's a specific format in a body potential footer.

That to me seems like I'm gonna have a lot of trouble keeping track of all of the details here. Is this something that you're concerned about in your own? Like, I I know I have, like, I have memory issues where I'm gonna forget all of the the structure of this kind of thing. In fact, when I think about BEM, I have to, like, go through my brain. Alright. Block. Like, what is the order that they all go in for for BEM? Yeah. So, like, for people who have a hard time remembering, like, really specific orders and stuff Like that, do you do you think is that gonna be something that you're gonna have a a trouble with, or you're just gonna pipe this into your brain and leave it there? I think I think you'll you'll get to to know it because It's like Git committing and things like that, but, like, I think I'm also thinking now, like, could there be some sort of, like, CLI

that Prompts you for each of the pieces. There's a Versus code extension I saw. And when you do a commit, it will prompt you for each of these 1, 4, or 5 different pieces of information. Yeah. I f. Actually, it's funny you mentioned that because I had just Googled conventional commits CLI to try to find the same thing, and I found,

which It it does is this exactly what you're referring to. It's basically prompts that are saying, oh, hey, dude. What it what type of release is this? What does this do? Whatever.

But I did all This is what I want. This is what you want. And there's also another one. It's c z c l I, which is also a conventional commit CLI, which looks like it has quite a bit of people used to 10,200.

Oh, yeah. We're late to the game on this, Scott. Late to the game on this, but

let me tell you, I also installed the the conventional commits GitHub extension or I'm not the GitHub. The Versus Code extension. And so you use standard command shift p conventional commits, and then it gives you a drop down saying, what Type is this? Is this a feature? Is this a bug? Whatever. And then it asks you for the scope. Alright? And I could say no scope, no scope 360.

It asks if you what kind of emoji you wanna give this? Oh, that's great. This Versus code one asks you if you want the lipstick emoji or the rocket ship emoji. Okay? Then write a short, tent it says tense description, but maybe it means terse.

Either way, it write a description.

So I did this, that, whatever, and it's gonna create your commits for you. And to me, that is such a better way to do this than me trying to remember the actual syntax for conventional commits. I think this to me was the biggest barrier for this because I would look at this. And let me tell you, the The documentation for conventional commits, yeah, it's pretty easy to parse. But if you look at this page, it can specifically be a little bit Overwhelming. If I look at this, I can look at it, and I would say, oh, wow. There's a lot to to learn here. But Yeah. If you install one of these CLIs or tools, hey. That that's all of the, the the The hard stuff out of the way for me. Let's talk about SemVer real quickly. So SemVer is you know, when you see, like, a node package and you see, like, 1.5,

0.2? You might be wondering, like, look. What are those numbers? December is broken down into the 3 major 3 major parts. There's fixes, which is our So let's look at 1.5.2 as an example. That 0.2 was released because they released 1.5.1 And, subsequently, 1.5.0, and then they realized something was broken. So they fixed it and released a dot release, which is that. The 1.5 part, The the 0.5 is they were on 1.4, but they added some new functionality to it, but they didn't break Anything else. So that they went from 1.4 to 1.5 because now there is this new method that you can you can go ahead and use.

Finally, the the one point, the very first one is breaking changes. So let's say they release something that totally broke how a method on the API worked, Then they bump it to 2.0 to 0. And this is kind of associated with conventional commits because you have fix, Which is patch releases, the the very end of it. There's feature, which is adding new stuff. That's the middle. And then you have breaking changes, which is The main one. So you can you can associate these and and probably even generate your SemVer version for your package

a. Based on the tags that are in these commits. Yeah. You know what? I'm really interested in that because if you were to look in the level of tutorials, GitHub issues right now, you would see one that says Automatic versioning, and then the body of the issue says, I'm really tired of having to change the version myself.

So I really think that this could be actually something that Could help us out in that regard. I'm I'm really excited to give this a try. I know we are definitely late on the boat to this one. The bolt pulled up and left, and now we're, like, trying to we're saying, wait. Hold on. We're gonna miss the boat. Looks like there is a already a package that will, Based on the commits, we'll generate a semantic version for you and automatically publish to that. If you go to the bottom of this conventional commits .org.

There's tooling for conventional commits. There is one that's just called semantic versioning, and it will automatically and I need that because I've got a couple packages on npm, and every single time that I have a a change to 1, I have to, like, bump it myself, like Scott just said, and publish it myself. And Automating that would be would be really slick. Be really slick. And, also, it would it would go really well with just everything else in my workflow, especially like we mentioned in Sentry because You can, you know, attach errors to versions. Right? Whenever

I get an error in my Sentry, it tells me what version of the software it's on. And if This is all done automatically, and we could have version updates, micro versions much more often when I'm not like, every commit or whatever Orvie, Ivery, whatever. It's really gonna nail that in just a little bit more, and I think that sounds fantastic. One thing I do wanna shout out here in this conventional commits.org is just how Awesome. This documentation is because they do everything in, like the body of it's in, like, a big FAQ, essentially. I mean, besides the the introductory stuff, It it teaches you the spec, whatever. But then there's a whole FAQ. And then below that, there's some resources for about, tooling for conventional commits of which there is a lot. You can always tell when something is highly used by how much tooling there is around it. And then project using conventional commit, so you can check out some people who are using it and see what it looks like in action. And to me, this is like gold star documentation. I really love this. I I I think that it is gee, just the amount of tools and and features around this stuff really gives you a good idea of why you should use it, And I think people should take notice about just how neat some of this documentation is. It feels like you know those, like, awesome GitHub repos where it could be, like, awesome conventional commits? This to me feels like Yeah. That repo as the documentation. I wonder if that is a thing.

Yeah. Right.

Yes.

There's not. It's because the docs are an awesome list already. Whenever I learn anything, like, the first thing I do, awesome blank. I mean, I'm I'm doing a lot of Deno right now, so I was doing awesome dino, and then you get all the awesome stuff right there. It's almost like it's in the name.

Alright. I think that's it. Scott and I are gonna try it, and maybe we will I don't know. Maybe 6 months from now, we'll do a follow-up show to see how we liked it, when we didn't like it, and if it made any of our our workflow and lives easier. Yeah. I am very excited to do this, and I'm I'm on board. I'm a 100% on board.

Beautiful. Alright. Well, thanks so much for tuning in. We will Catch you on Wednesday.

Peace. Peace.

Head on over to syntax.fm for a Full archive of all of our shows. And don't forget to subscribe in your podcast player or drop a review if you like this show.