200: Keep a CHANGELOG
I think you should keep a change log. It probably should be a markdown, and I think it should be called changelog.md. But what should be in it? In this episode, I interview Olivier Lacan, the creator of keepitchangelog.com, which is a really great reference for what you should and should not put in your change log. Welcome to Test and Code.
Brian:I am thrilled to have Olivier Lacan, and I I'm sure I mispronounced your name.
Oliver:You actually didn't. Okay. That's pretty good.
Brian:So is that is that French?
Oliver:Yes. I'm from the France.
Brian:And you're also from the the land of sky blue waters or from Ruby Land. Mhmm. Is that where you spend most of your time?
Oliver:I don't know that there's anything sky blue about it. It's more it's more ruby red. There's there's issues sometimes. But, yeah, this is my community of of choice, that I fell into. Yeah.
Brian:Oh, I asked you on because I, because I I have in the next couple episodes, I'm gonna talk about a couple tools around keeping a change log. And and I've been referencing a website called keep a change log for a long time. And it's just, it's good to have them. This website here, just as, you know, if people ask me why should I keep change log, I just put them here. And I think a lot of people do.
Brian:So we are gonna talk about that. But then when I was researching this episode, I found out that you're a Ruby developer and you're also the same the person that started shields. Io, which I think I probably use on at least one of my projects. So that's kind of a neat thing. So first of all, welcome, and, Olivier.
Brian:And other than being a Ruby person, who are you?
Oliver:I'm a I'm a French person. That was the the early the early thing. Some people don't believe that, because the accent is not as obvious, but very, very French. I would actually move to Florida, yes, when I was 23, I think.
Brian:Oh, wow.
Oliver:I went to school there. And and originally, I wasn't I wasn't a student of computer science. I actually I've never been a student of computer science. I just went to kind of a practical web design development school. And I I was a web designer.
Oliver:That's the thing that I learned on my own. I was just I was really web design focused, which actually informs some of the conversations that we're gonna have, notably Shields, but but also keep a shingle on because as a web designer, you know, in a sea of programmers and and web server people, it can be really hard to kinda, you know, understand what's going on. I just remember how lost I was just trying to use software to learn how to put up a website. And a lot of those software packages or, you know, sometimes zip files or just random scripts you'd find would have very, very limited documentation. I just remember how hard it was for me to try to cross the Rubicon of being a, pun intended, the of trying to be a Webby person, but wanting to make a server run or wanting to talk to a database from my HTML or, you know, from my front end.
Oliver:And it took a lot of effort. It's easier now, but it's still really tricky to know what's going on when you land on a on an open source tool, which is Yeah. Why these two projects exist, honestly.
Brian:Okay. Which and, which was the the first, or are they kinda around the same time?
Oliver:Shields was the one where I think I was working at Code School at the time. So I was, there's a company, in in Florida, a consultancy that did Ruby development and dLabs, and they did a lot of kinda, like, high high profile, like, big Ruby sites. And they had to kinda explain the same stuff over and over again, how to use either Ruby or Rails. There was try Ruby exist at the time because, the the community was fairly friendly to beginners on the Ruby side. But on the Rails side, it was very kind of like, you know, Heroku, I think, helped some people get started with Rails, but it was just kinda rough.
Oliver:So I think they they for a conference for, I don't know if it was RubyConf or RailsConf or even OSCON. They created, kind of a boot camp version of of what became, the learn by doing approach of, like, I show you a video really quickly, and then we're gonna hop in the browser and then actually write some code rather than, like, try to do it on your machine and then waste a day trying to get in dependencies installed. So that's where I worked at the time, and we did a lot of stuff with open source, you know, software. And we also developed courses really quickly. So we'd kind of, like, get in the weeds of, like, oh my god.
Oliver:What did we use on this version? We had to upgrade. And we had to do a lot of platform upgrades and a lot of open source, you know, package upgrades. And it was just really, really hard. And it was around the time where code, I think code metrics stuff startups started popping up.
Oliver:Code Climate was popping up. Travis CI was popping up. So a lot of CI tools would show up on read me files. So you'd start seeing these, like, kinda like it's kind of like WebRing, you know, forum badge Yeah. Looking things show up on readmes, and they were really ugly.
Brian:Yeah. I think actually, I think Jenkins is the not Jenkins, but but Travis was the first one. First time I used a badge was to show what the test were you know, the test result run was from Travis.
Oliver:I mean, the the intent made sense. Right? Like, it was it it was logical to wanna say, hey. Here are the tests for this package. Like, look.
Oliver:We have tests. Like, they're and they're just we have tests, but they're running and they're passing. And that was the cool thing. Some of them had a status, which is really cool, and it was kinda static. It was like a red or green or something like that.
Oliver:And they just had PNGs or or or GIFs even sometimes. And then what really started to get under my skin is I started seeing people use Readmes as an ad platform. So these badges started turning into, that's my startup here. Like we made a thing and it's called and it didn't provide any value. It was just a logo.
Oliver:And there's just a huge one missed opportunity to, you know first of all, missed opportunity to provide information that's useful to the actual user of the Readme
Brian:Yeah.
Oliver:And be like, this is tests are good. This is the version number. This is what we support, like a version of Ruby that we're using, a version of Python that we're using. And it was so so obvious that people are missing that. And the other was like, you're kind of being hawkish.
Oliver:Right? You're hawking your your thing, and it's just kind of gross, and it's making me mad. So quite literally at, like, 11, I think, or middle of the night. I was just like I wrote a blog post called an open source rage diamond, and I think I have the time stamp of the first commit on shields, which was January 29th, 2013 at 11:55 PST. So it might have been, like, even later in the night because I was in Orlando.
Oliver:So super late, really cranky, and I just I just wrote one commit that was a readme and a PSD. And the PSD was just I think you can actually see PSDs or, like, Photoshop files in, GitHub now, but it was just a homogenized, well designed, rounded edges, neat, like, key value, legible typeface, normal size, not too big, not too small, just at at at 16 pixels or something like that. It's a really small thing. And that's it. That was the beginning of the project.
Oliver:And then I just the rest of it was convincing people, like, please please stop using these ugly things. Like, provide value. And we had so many conversations with a bunch of different companies. I think Travis and Code Climate and, a bunch of hosts, like package hosts for Ruby, I think. Okay.
Oliver:That's all that
Brian:But there's so it's grown to be a lot of stuff. So you've got different shields for or maybe these are just examples, or are they free form? No.
Oliver:They they actually fully formed. So this is I just told you the genesis, but, like, the part where it was wild is when you have an idea, a lot of the time, you you think, like, this is such a great I didn't think this was a great idea. I I just hated I hated what the reality was. It just made me mad. So I just said, how about this?
Oliver:What what if we do this? And I made the repo like cc 0 public domain. I don't want credit for this. I I I just want people to not do this other thing. Please, I tell you.
Oliver:A bunch of people that I knew or even didn't know on Twitter and GitHub and other places were like, oh, I like that. Oh, I like that. So they helped me either make PNGs by hand out of that PSD, which was a nightmare, by the way. Completely didn't scale. And eventually, a bunch of really smart, like, dedicated people made different implementations in different languages, which is really interesting because you you would assume as a Rubyist, I would be like, probably, let's do that.
Oliver:I'll make a I'll make a server that just makes these images in the background. Yeah. Didn't feel like doing that. I honestly, I had so much stuff to do at the time that I I just didn't have the capacity. So I asked, and it turns out a bunch of people already did that.
Oliver:There was a Node version. There was a Python version, I think. It might have been a PHP version. And in the end, I think the one that won drum roll. Can you guess?
Brian:Don't know.
Oliver:See? Node. It was Node. I think it was Node because simply because there there was a lot of excitement in that community at the time. So there were I it it was a really, really nice developer too.
Oliver:It wasn't just the technology. It was the person who did it was super nice and, helped a lot with setting up kind of, like, the basic foundations of an API called nowadays, img.shields.io that you can hit with very simple query parameters to retrieve. So if you click on any of the examples you see or there's even a a badge generator on shields. Io, you can put a label saying, like, hello, and then a message called world, and then you just pick a color, bright green, boom, and then you have a badge. And it looks great.
Oliver:It's literally I m g dot chills dot I o slash badge slash hello dash world dash bright green. And it's a it's brilliant. It's simple. It's you know, parameters do it what they're supposed to do. You can make it, you know, more complicated than that.
Oliver:But if you have a website or an app, all you have to do is just, like, put that in. It's cached. Really, really smart caching logic. And then that's it. You get the value that you want.
Brian:So, like but okay. So for things like like, go back to my, like, testing status or something like that, test results, I don't actually wanna write the hard coded Yeah. Description of it. I want it to look somehow it to look up from the results. So who's doing that?
Brian:Who's it like
Oliver:It's contributors. Honestly, I mean, there's there's maintainers like with it. Years years, it's been I think it's been 10 years. We just celebrated the 10 year anniversary in February, I think. But, yeah, 20th, 2013, 2020.
Oliver:And, originally, it was a bunch of people submitting PRs and saying, here's an adapter that looks up the organization name, their repo name on this thing and figures out, like, okay. Where's the CI? Is it running? Is it not running? We also did a lot of collaborations with different vendors to actually get them to implement.
Oliver:Like, either they go out to shields and make the badge, and that way you can use it there. So it it varies among supports for different platforms. But if you look on the website and you click on, say, builds, there's so many providers. You know? Travis, GitHub, Drone, Codeship, Cyrus, Azure, like, just everything you can think of that were integrated TeamCity even.
Oliver:And there's so many categories like yeah. Yeah. Dependencies, downloads, funding, all of these things that you might wanna say about your project in a kind of a concise way. And the the pitch that I gave to so many of those companies was you're gonna get traffic. The people are gonna see the value you're providing.
Oliver:Sure. It's not plastering your logo on the read me, which might be less fun than your marketing team wants. But but the people, if you do good stuff, they're they'll come to you. They'll click on that, and now it's both actionable as in there's is an action you can take on the on click on the read the read me badge itself, but the data in the read me is helpful.
Brian:Yeah. Yeah. And then it's like, it's opt in advertising. So the the person with the repository, the open source maintainer, gets to decide, do I am I okay with linking to this service? Yeah.
Brian:And if I'm getting value from it, then, yeah, sure. Why not?
Oliver:And they decide. Exactly.
Brian:Yeah. But, also, I don't really wanna have it be too spammy because I'm as a maintainer, I'm not making money off of this and Right.
Oliver:Or anything. So yeah. And it makes you look bad. Eventually, you know, you you want people to be attracted to your project. So what still to this date, it kind of works fine.
Oliver:But at the time, we had conversations with people at GitHub, and they were saying, like, oof, we don't know if we wanna do this because eventually, the first API to make a a dynamic badge ended up being XML. Right? You use, underlying SVG, but it's XML. Right? So Okay.
Oliver:So the code that actually makes these and I had an an an amazing epiphany moment the other day. I went to GitHub to set up an action, and then GitHub prompted me, do you want a badge? And I was like, wait. Hold on. Does GitHub have badges now?
Oliver:And so I I loaded the badge and looked, you know, virtually the same as the original design that wasn't just I didn't come up with it. I just refined something that was already kinda there. The you know, it's gray on one side. It's green on the other. And I I just couldn't believe how close it was, so I loaded the source code of the SVG and compared it to the shields dot io output, which is I don't I don't I don't maintain that anymore.
Oliver:It's it's a bunch of really, really cool people that that work on this, but it looks virtually the same. Like, if you look at the source for these two things, it's basically they followed the convention. Right? They just, like they I don't know if they use shields, and they probably don't want to depend on that because I think the worry at the time was, oh, it can execute some stuff. You know, it might be a vector vulnerability and might we might not wanna be involved in that.
Brian:Yeah. But it's kinda cool that you've you kinda open that up to say, you do it yourself if you want, but, this is how it should look and this is how it should behave. So that's that's pretty cool.
Oliver:And you yeah. It's surprising how often these tiny nudges, aren't on the radar. They're the companies or the services that you're and a simple suggestion like, hey, have you seen this? This is helpful. It goes a long way.
Brian:That's Shields. Io. And Keep a Change Log, how'd that start?
Oliver:I think that it started with, reading 100,000 read mes and trying to find change logs or history dot MDs or, you know, all the other names that people have used throughout. So there's big religious debates about how to name these things, and that's actually one of the reasons why it's so hard to find them. Right? Like, what is it gonna be called? Is it gonna be releases?
Oliver:Is it gonna be history? And I had because I was maintaining codeschooldot com, like the platform, I had to do a lot of platform upgrades with, you know, peer dependencies that are blocking some very important platform upgrade that you wanna do to this new framework or this new language. So you have to read a lot of ringmes and a lot of, release notes. And it just it just got so exhausting. I remember, my at the time, almost coworker, we, we worked kinda like across 2 companies that were sister companies, NV Labs and Code School.
Oliver:Nate Bibler, who was a long time Ruby developer at at that company, had kinda, like, made a guide to finding good dependencies for Ruby, in which he said specifically, look at the change log. Like, it's helpful if that change log is like this. And, also, when he produced, you know, the packages or the Ruby gems in this case, he was very methodical about putting a version number in, a markdown file that had a heading with, you know, the the version number dash the the date time it was released, and then a bunch of bullets that explained very importantly if there's breaking changes or if there's, like, major, new features or something something like that. And I kind of took that mold and said, okay. If I explain to people why it's like that, I think it'll help.
Oliver:Because it's not just copy this thing. A lot of people do that. But here's why it's not all your git commits. And a lot of people were doing that at the time. They were dumping.
Oliver:That's why the the tag the tagline was, like, don't let your chain like, I forget I forget what I wrote. Don't let your friends dump git logs into change logs because that was just normal. Everyone did it. It was like, oh, here's a change log. Even Ruby did it.
Oliver:The Ruby release notes were just a dump of all of the com it was just impossible to parse then because they were really busy, and they had a lot of things that changed.
Brian:I'm actually seeing that even more in internal project as well. Internal. Yeah. Yeah. Not a source project, but internal.
Brian:You've got, and these are these are, like, change reports that really only go to internal people, but the internal people aren't necessarily gonna care about all the detail. It's the Right. You have to write. And that's one of the things. So I'm also gonna link to you did a great interview, and this is way back in, what, 2014 or something like that, with, with the change log team.
Brian:The the, that's funny. Got kinda meta. It it feels like it was
Oliver:a couple weeks ago and yeah. Yeah.
Brian:It was a, great interview, but you go through all all the, like, tons of the history and and talking about it a lot. But one of the things that you brought up that I wanna highlight is the audience is different. The the or at least the it might be the same audience, but the mentality is different. When you're looking at a change log, they're, like, notable changes from the outside, whereas Right. The the detailed commit messages are the nitty gritty, what deep what bug fix and all that sort of stuff you're on.
Brian:Although keeping putting bug fix numbers in a change log as well, I I assume you think that that's a good thing.
Oliver:I only think that's a good thing if the bug fix is something that's gonna provide context to something that you alluded to. So say you say there's a notable change. Right? This is the kind of the it's the test. Right?
Oliver:What's what's notable? And people are, I have no idea what notable. Well, okay. Would you mention it to someone, a friend specifically? If you said, just go upgrade on this version of React, is there anything that I should be aware of?
Oliver:That's notable. Right? Yeah. If if it doesn't matter, then it's nice. It's a great internal refactor.
Oliver:It's amazing that you, have fewer vulnerabilities, for instance, to other peer dependencies. That's great. But that's not gonna change necessarily necessarily the experience of the person who is upgrading to that version. So you wanna make sure that all the landmines are labeled essentially and not just what you think is gonna be. So for instance, one of the things that I think I we highlight in the in the guideline is if you add a feature, that's a potential regression.
Oliver:Right? So it's not necessarily a breaking change, but if you mention that you've added a new logging system and I use my own logging system that may interfere, I'm gonna be on the alert. I'm gonna be like, I'm gonna be careful when I run my test to make sure that these loggers are playing nice with each other and no one's not on the same namespace, for instance. And that's, to me, like, a great example of why mention why have all the categories maybe in your head all the time? Added, removed, updated, you know, and and breaking change, labeling, stuff like that.
Oliver:So that's why we we have a bunch of, like, baseline categories that we recommend, like, you know, deprecated is nice. Like, it's gonna come up. Be aware of it. You know, you're upgrading to this version. You're gonna need some see some warnings about this is going away soon.
Oliver:And that's kind of the establishing a relationship with the person consuming your releases. Yeah. That they know where to look.
Brian:And I I kind of alluded to it or we we have, but I think I I guess for people that haven't read this this keep a change log or aren't familiar, this is a kind of a standard that says, really, you should describe what you're doing or describe what the change log is at the top. There's a text format, and then it's kind of a markdown format, or is it I think it's markdown, that says specifically that you're what what what your you know, the list, the version, list the, the date in a specific, like, sane date time format of, like, year, month, day, and then groups of categories of added what do you got? Added, fixed, changed, removed, and then bullet points under those. And then you can have, like you said, you could have more or you could have deprecated, and that's a good thing to do. But I love the category ideas because and, also, this goes, like, most recent to older.
Brian:So you can look at the top of the file and get the Out of the chronological. Yep. Yeah. I have seen the seen the opposite of people, like, doing there's other things that and it always comes becomes problems. If you put the newest stuff at the bottom, then everybody has to scroll to the bottom to see what the newest stuff is.
Brian:That's annoying. The other bit is, I've seen places where they'll have a version, but then the bullet points have, like, tags in the middle. Like, added like, each of the bullets has, like, a label Yep. Within it, but that's hard to scan if there's a lot of stuff.
Oliver:Mhmm.
Brian:And You're asking people to parse
Oliver:your change log for you. Right? You're asking them to do that difficult you can automate that with very little work. Right? It's just like scan for the word added and stop saying that, group it under a heading, and then boom.
Oliver:If I only care about what you added, then you've you've made my life so much easier.
Brian:Well and and also even it could be the same person. So if I'm looking at another project Yeah. And I thinking about upgrading, The first thing I I'm gonna look at probably is what cool stuff. Was there new cool stuff?
Oliver:Exactly. Yep.
Brian:Also, is there some major bug fix that I really should care about that maybe I don't care about, but I should? And then and then right before I actually pull the trigger and upgrade, I'm gonna go wait a second. Am I using anything that's been removed or deprecated that I need to be aware of? And also just to be honest, I'll probably skip that part until my tests fail. Exactly.
Brian:And then when my tests fail, I'll go back and go, oh, did did did something change that I didn't pay attention to?
Oliver:But there's a place for you to go, and this is kinda, like, seems almost so obvious these days. And it's just like, it's only 10 years later, basically. I don't know what date. You asked me what date it started. I think 2015 is when keep a change log was first.
Oliver:So it it was only a year or 2 after, maybe 2014. So it's not that old, and we can easily see it because there's a change log. So the first release yes. 2014. The first, like, point release was 0 0 1 in, May 31, 2014.
Oliver:So we're 9 years. And it was very, very basic too. But like the central almost religious debate that I had with people saying, like, I know there's news dotmd or news dot txt is one way to say it. There's so many other ways to call the file. Just call it a changelog.
Oliver:Routinely, in vernacular, when we're just having conversations among developers, we don't say the notes, the news, the whatever, the history, we say the change log. So if you name it that, it'll stand out in the, in the root of your project. And if you don't, then at least, you know, as long as there's at least a place where we're in good shape, right, there's at least a place you will go back to when your tests are failing. But that's even asking a lot. A lot of people would not have that file.
Oliver:Big projects sometimes, like, I remember OAuth integration, packages that I I was using at the time didn't have just didn't bother. It was like, oh, just read the commits. OAuth. No. Come on.
Oliver:Like, you're you're essentially so I think Nate at the time kinda gave me the idea, because of him describing, like, things you can trust. Right? You look at maintainers. You know how many issues are open, kinda like the the typical kind of tentpole. Oh, is this a good project, bad project based on and there's a bunch of tools that automate that now, but I think it says a lot when you're saying, before I release this thing, I'm just gonna skim through all we did and just give you a little little summary, categorized, dated, that you can refer to.
Oliver:And then there's other extra features that are in the the changelog guidelines. So I describe them as guidelines more than a standard necessarily because I want that barrier to entry to be as low as it can possibly be. I don't want you to fail a parser. I don't want you to get mad and then bike shed your change log so that it has exactly the right formatting. I just want you to have one.
Oliver:That's why it's called keep a change log. Just just keep it.
Brian:So and one of the categories at the top is is, not the version, but unreleased. So, should this be being updated during commits, though, then? When when does it update?
Oliver:It depends on what you do. Right? So if you have maintainers, and you're a solo team developing your thing and you you don't have contributors so internal projects initially, I just meant for KeePass Chainlink. Yeah. Most of these both projects were intended for open source, but I quickly realized that a lot of people were getting values from this across the board, partly a closed source and other kinds of projects because, you know, they have to manage multiple maintainers or multiple contributors, I would say the unreleased section is best for open source projects once a PR is merged, once a a larger unit of contribution is merged so that you can say, okay.
Oliver:Well, that unit of stuff is definitely notable. Let's put it unreleased so we remember to talk about it in the it's kind of a staging area, essentially, so that I don't have to reparse everything that happened, make your life easier. You don't have to use unreleased. But it's also nice, say, in your case, when you're looking at upgrades that you're making to some packages or even a language, you can be like, oh, the tests are failing on this thing or it's passing on this upgrade, but the next one that they're working on, if I check out, you know, the main branch, they're gonna change a bunch of stuff that was deprecated because it's in the unreleased section. So I'm gonna get ready for that.
Oliver:Yeah. Super helpful.
Brian:Also, one of the things you mentioned in the other interview was, curating it. So, I like the idea of doing an unreleased section just so that once things it can actually be messier. Not not it isn't all the commits, but it could be messier than the stuff in the version releases. Because once you decide on a version, you can go through that whole list and go, is this really notable? Do users really have to care about it?
Oliver:Exactly.
Brian:And edit it there. So that's cool.
Oliver:I think that that was that was a section where a lot of conversations happened because of merge conflicts. A lot of people were were, concerned about encouraging people submitting pull requests or merge requests, putting changes in change log because if it if they do it when they checked out the main branch and then the main branch diverges, then you get to resolve these fun, line by line, you know, problems. So if you do unreleased, at least all the problems you'll have will be in unreleased. Right? So I'll be at the top of the change log.
Oliver:So it's a little easier there. You can also say it's not your job as a as a contributor to update the change log. That's my job. Or we do it at the end when we're rebasing Yeah. And combining everything.
Brian:Well, actually and so the a couple of the tools that I've been looking at are around this this idea of, if you're you're gonna if everybody's editing this one file, then you're gonna have merge conflicts because they're all editing the same, like, top line thing. So, I I was gonna ask you, we were briefly talking about this before we started recording. What are your thoughts on that? What are your thoughts on the tooling around changelog?
Oliver:For that particular example of managing, you know, churn on the file itself, I I get it. I'll I'll give you the skepticism I had way back then was people have this reactive instincts to just wanna just put tools on everything. This is not a tooling issue. This is a human communication issue. This is you not taking the time to just slow down and synthesize as a human would.
Oliver:Now if you want to go use chatgpt to summarize all the commits and and it comes up with something actually that you feel like, wow, that's actually pretty good. That's how I would describe. Go ahead. Automate that. Use that API, send all your commits, get a summary where it does the job for you.
Oliver:But that's the thing is a lot of these tools constrain you to change your process to become basically, the output of the change log is everything that matters, not what you're working on. And and I have I thought it was a bad idea at the time, and I didn't have evidence after working for years using, and I'm not trying to say bad things about people who like commits to be formatted a certain way, but after using commit formatting tooling for work for years with teams of highly productive people, the constant friction they cause when you're trying to describe a commit and say, this is what this means, this is what this change is, and now I have to put a little namespace or explain what kind of change it is at the time you're making the work is not the moment I want you to be necessarily thinking about the change log. That's that's not the time. And you end up stepping into the rug.
Brian:Yeah. Okay.
Oliver:That's not to say that they're not really, really good tools that, for instance, will say, unmerge conflict something because, someone you've you want your contributors to add a changelog entry. It'll figure out, okay. They had checked out the old version of main. We'll just shift stuff around and make everything better and then fix that for you. Completely understandable.
Oliver:Glue stuff and and just quality of life stuff, I completely understand and encourage. But what I mentioned prior is the reason why I never added a tool section to to keep a change log. And I might, in, you know, the next major version, only to say what I just said to you, which is, like, there's a place in time for tools. Remember the goal is not to make yourself a slave to the change log.
Brian:Right. Yeah. And it's it's, the point is communication. If and if the solution is communicate with everybody better, maybe that's it. I've had a project projects open source projects that I've worked with where the the change log entry comes in at the review where, somebody's Yeah.
Brian:Made a commit and and they get encouraged. Wow. This looks great. You you know, you you fixed the thing. Thanks.
Brian:We're about ready to merge it in, but we'd like it to describe it to the end user. Can you write a little snippet to say, you know, how this can be used or something? And and I think that's a and, like you said, during PR time, pro request when you're about it doesn't even have to be at the beginning of the PR, but when it's about to get accepted, that might be the right time to think about how you're gonna describe the change. So it's good.
Oliver:It's it's definitely better at the end. I've seen that happens in larger projects like rails, for instance. Like, they routinely say, hey. Hey. Hold on.
Oliver:Hold on for making first of all, we haven't merged it yet, so we don't know what it's gonna actually look like. So maybe you're doing this work for nothing. Right? Or you'll have to change so much of the feature that you're submitting that you'll have to redo the change log entry anyway.
Brian:Yeah. Okay. So you mentioned a future version. So is there a version that right now, we're at, like, version 1.0. Oh, it's 1.1.0.
Brian:So That's right.
Oliver:So that that So It's a very minor upgrade. So the the big change in 1.1, was to add a, I think the section where we're talking about inconsistent changes, which is the kind of realization that, hey, versioning a thing that you've asked people to translate in 25 languages, it's hard. And so we realized, if I add one category, I'm basically invalidating the version for every other language. So I have to be a lot more purposeful, and this is why the project hasn't, you know, changed the language so much, but just simplify the process and and try to get as many translations as possible. So I think I mentioned to you, it's it's translated, and I tried to count earlier.
Oliver:I I said it in the email when we talked to each other, but it's, like, more than 20. I think 22 or more. And and we're talking, like, not just, like, Spanish and French and obvious ones, but, like, it's it's translated in Turkish and and Chinese and Japanese and, like, Russian and so like, just like so many. And this is where the the that blows my mind a little bit is that when I say I want the bar to be low, this is exactly, I think, what I never dreamed of hoping for, is that it would be accessible enough of a guideline that you get people from all over the world kinda looking it up. And sometimes I check curiosity, just like checking, like, referring sites and, like, where where is traffic coming from?
Oliver:And see, like, just dev.azure.com, for instance, like bitbucket.org. Like, big, you know, companies that do code hosting or things like that saying, like, check that out. And I feel like, okay. Well, I I guess I guess we did something. Right?
Oliver:Yeah. The other ones were, I think, the the digital service or, 18 f, the the USD digital service had kind of like a guidelines for developing internal tools or even just, like, public facing tools that reference keypad change logs. So did the the the UK office for the same and it just it kind of melted my brain because I honestly, this is one little website explaining a format. Yeah. It's a beautiful website, by the way, that was that was designed by, Tyler Fortune who was a coworker of mine, at Kutzgold and Pluralsight for a long time.
Oliver:And it it's, you know, it's digestible. It's that's about it. Yeah. But the amount of I just just to give you a basic idea, I think in the last years, last few years, it's about 200,000 people a year, like, peruse unique people peruse keep a changelog. And I don't know how many of them.
Oliver:I think I've I've done searches on GitHub to see because people people sometimes link to this is following the format from keepitchengnich.com, so you can kinda search for that. And there's so many results. And I think that's a direct consequence of making it simple and not having so many hoops to jump through to support, that people can adapt it in the ways that make sense for them.
Brian:Well and also, like, as a project, I don't have to explain why I'm formatting this way. I can just say I'm doing that.
Oliver:You wanna
Brian:know. Go reread it.
Oliver:Right.
Brian:Now So we're working.
Oliver:So, yeah, it's for next versions. Do you yeah. Specifically, the next
Brian:versions order? Like, are you gonna do, like, the newest last on the version 2?
Oliver:Or So let's see. That that's it's I I I would never do something like that. I think what we'll do is probably more focused on making translation updating easier. So it's gonna be tokenizing. So there's some some really interesting suggestions, especially lately on terminology.
Oliver:Right? So it's really, really hard. And for I didn't like, my professional career started in the US. So I it's it's so hard for me. I that's why I didn't translate keep it in French myself because I I have no idea how to say most software development things in French.
Oliver:And even in I think if it's Russian, someone submitted something saying, like, we don't use Russian to describe changelog entries and, you know, the categories. We use English because that's just the lingua franca. So while the explanation is gonna be in Russian, the title and headings are gonna be in English because, obviously, most software is written in English, I think, at least in a large part of the world. So it's gonna be things like that. And I think at 2.0, I'm also going to try to, like I mentioned, talk about tooling and, and give people the pros and cons there.
Oliver:Not link directly to specific tools, which a lot of people really want a recommendation from the project on tooling. The tooling always evolves, and it's it's a moving target. Whereas, like, the simplicity of this, I think, yields yields best results.
Brian:Well, if you're a Python developer, you just and you're worried about tooling, just listen to the next two episodes.
Oliver:Nice. Nice. Speaking of teasing. And then if you're if you're a Ruby or a Rails developer, it I believe that Bundler, the packaging tool, actually encourages you to have a code of product, have a release, you know, a version number and all that that stuff. But I think if you do bundle init I haven't done it in a while.
Oliver:But if you, yeah, if you type, bundle init, which is how you make a new Ruby package with bundler, And then you go through the process. It encourages you to do these things. Just like, hey, do you want to make a change? Do you want to make a license file? Do you want to make these things?
Oliver:I think those are great tooling integrations, essentially, or nudges to to use good practices.
Brian:Yeah. Well and there and there's some of those growing. There's there's a handful, and they're growing, tools in the Python community to essentially help you initialize a project. So the the the tough part is is the what kind of a project is it? Yeah.
Brian:Because people that are library developers think everything's a library, and people that are application developers think everything's an application. And then there's just script writers that just want, like, a little script and That's
Oliver:what we
Brian:did. Yeah. Yeah. So
Oliver:The portability is one of those aspects relating to tools. Right? Because a lot of so a lot of people recommended tools that were, like, community tools. Very interesting. Check it out.
Oliver:Try it out. See if it works for you. That's that's my recommendation. There are tools like GitHub that do things kind of like Keep It Changed Log. Right?
Oliver:There's GitHub releases, which has been there, I think, almost as long as Keep It Changed Log has been a thing. GitHub has had a release section they added to where tags were for Git tags. So you could tag things. Initially, it was just tags, and then they made it a section where you could draft a release and then associate a release with notes to a tag. That was a kind of headache to think about back then because it's a really awesome feature, and I want people to do things more easily, but it's not portable.
Oliver:Yeah. So wherever your repo ends up, you'll have to reproduce this GitHub releases kind of section, or you'll have to maintain both and have the change log be a text file in your repo and kind of copy that stuff over. So here, tooling may would make sense for me. Right? So if you have a source file that's portable and you wanna maintain that and copy that over to GitHub releases or GitLab releases, that makes sense to me.
Oliver:Right? So you don't have to do the same thing twice.
Brian:And then there is tooling to take the releases
Oliver:and And do the opposite.
Brian:Yeah. And create a change log from it.
Oliver:And I guess that's fine if you want that to be your canonical source. Yeah. It doesn't make sense to me, but sure.
Brian:The and the one of the things I heard, can't remember who I heard it from, was, in discussing this is that, there's a lot of history and everything, commit messages and everything in Git. But Yes. The we should have enough documentation with the source code itself so that if you take, download a zip file or, of the repository or do a shallow clone
Oliver:Mhmm. Telecom. Yep.
Brian:You have enough information to continue the project without the history. So
Oliver:And that that's why portability matters so much, I think.
Brian:Yeah. And I know I love that because I I actually hate looking through history. I mean, the, like for instance, if in the upgrade model, if you're upgrading a tool from like very far, like long ago, try to this and it's not working. How far back do you need to go?
Oliver:So many pages. Yeah. Well click on next page on on releases so much because different releases paginate differently because there there's more text in them, and they actually paginate based on length of copy, not on number of releases. Right. I think.
Brian:Okay. But I'm just even thinking, like, I wanna I gotta fix my thing. I wanna upgrade, but I I I can't upgrade that far. Or where's the where where's the breaking change? And being able to look at a change log and go, oh, the feature that is breaking is this, and that was changed, like, 3 versions ago.
Brian:So I'll upgrade to right before that Exactly. And then and then step through it, so I don't have to do a whole binary search of the entire version trace.
Oliver:And the the tooling can find its way around good good documentation like this because Dependabot, for instance, was a Ruby based project that started reading. There's other projects before Gymnasium did that stuff like that, but it was like parsing change logs. You know, you don't necessarily need a hard format as long as it's separated in sections, you'll be able to say, like, okay. There's a date here and a bunch of text below. Okay.
Oliver:Can we diff that instead of diffing the commits themselves? And then now, Dependabot when it opens on GitHub, at least, I think I think there's similar tools, but it will tell you you're 15 major versions behind, and these are the changes in these 15 versions that actually are in the change log. Yeah. So you can just un I think you open a little detail, like, expendable little HTML snippet, and you can see they added this, and they removed that, and they deprecated this, and there was breaking changes. And it's such every time I see this, it's just I'm so delighted of the the, you know, the effort that would be just hours and hours of you parsing through that.
Brian:Well, I guess we should wrap it up, but I just wanna say thanks for making this. I think the whole world said, I don't know if I really care what it looks like, but somebody has to pick. And you picked, and thanks.
Oliver:You're welcome. And it's a it's a lot of contributions from a lot of people around the world. And and if you know a language that isn't in keep a change log or you're wanting to contribute in that way, the repo accepts, you know, pull requests for that. So it's very helpful.
Brian:Okay. And, we'll we'll link to the we'll have, some information about you in the link in the show notes as well. You looks like, you have, your name, Olivier Lacan.com.
Oliver:Super easy.
Brian:So that's easy. Nice. Well, thanks a lot, and, we'll catch up later. Thanks.
Creators and Guests
