The Changelog: Software Development, Open Source - Keep a CHANGELOG (Interview)

Episode Date: August 8, 2014

Adam and Jerod talk with Olivier Lacan about keeping a `CHANGELOG` and his passion for keeping a human facing, readable history, for software projects.

Welcome back everyone. This is The Change Log. We're a member supported blog, podcast, and weekly email covering what's fresh and what's new and open source. Check out the blog at thechangelog.com. Our past shows at 5by5.tv slash changelog. And you're listening to episode 127. And Jared and I talked to Olivier Lacan about keeping a changelog, just keeping your source in check so that everyone else knows what's going on.

Changelogs are important. We obviously think so because we're called the changelog, but that's beside the point. Today's show is sponsored by Top Tile ship and rack space we'll tell you a bit more about coach ship and rack space later in the show but our friends at top towel i gotta say something personal just for this spot here because um and many of you might know i work i have a full-time job just like many of you have a full-time job and that full-time job is purecharity.com. We do fundraising for nonprofits. Really cool thing we're doing.

We've been doing that for the past three years. But we recently had a need for a higher engineering push. And it kind of had to happen quickly. We didn't have a lot of solutions in place to go and find new engineers. We didn't have time to go and hunt people down and find the right people. So because of working with Top Top for so long here at the Change Log, I knew that they were the people we can trust to get some good answers. And so we put a couple of different job applications into top top for rails engineers and within days literally within days we had interviews with some of the best and brightest minds available for us um and we couldn't have been more blessed because we just finished shipping um in the next episode actually

you'll hear this harry mentioned how we were shipping and we we shipped this large project over a month and a half um after we hired guys from TopTile, two different engineers to come in and help out our current development team to add that extra oomph to our output. And we could not have been more happy. We could not have been more saved because of the great work and awesome abilities that TopTile has for matching up, basically. They're a matchmaking service. They match great developers with great opportunities and that's just how it goes so we came in and had a need those developers who had a need for for a position they had top title look to and we had top title look to for

finding the best and that's exactly what they do and they want you if you're an awesome engineer out there looking to freelance and do all sorts of cool stuff with cool technologies, and you want to find some really, really awesome opportunities, go to topside.com slash developers and tell them that Changelog sent you. Enjoy the show. Today we're joined by Olivier Lacou. Did I do good? Was it close close you did better in a in a in practicing i did yeah so long story short our guest is french so obviously his name is a little

difficult to pronounce um i'm here jared's here we're here to talk about change logging which is sort of meta in a sense and if if you know the voice of olivet then you probably heard it on ruby 5 you're prolific in ruby and you do things at code school so i'm sure you got your voice out there all over the place right sadly yes i talk a lot well in any case welcome to the show thank you and it's happy to be here it is sort of meta because um i stumbled upon this project of yours um which is Keep a Change Log. And the subtitle is Don't Let Your Friends Dumb Get Logs Into Change Logs, which I thought was pretty cool because we're the change log. And everybody who does open source or any sort of software really is to some degree keeping change.

Even proprietary software has change logs, right? So, I mean, this isn't just open source this is sort of software uh you know as you see it this is what see this is why i wish people would do but i realized in recent months as i was actually going through upgrading a lot of old apps a lot of apps that we have internally that people actually don't do that. People actually tend to think that their software maintains itself or as long as they contribute it then it's done and you don't really have to do the side work because it's kind of boring you know to keep a changelog and actually write down like a journal like

okay we did this this week and that week. Because it's just tedious. And people would rather be as impactful as they want to be. Even think about those who are shipping apps to the App Store, like Apple's App Store or Play Store. Even those apps, they actually, a lot of the developers have a lot of fun with these. I don't know if they're called changelogs there or not. Release notes? Release not, but. Release notes, I think they call them. Right. I actually have a folder.

But it's still the same thing. Yeah, I have a folder of screenshots that every time one of those developers makes an amazing changelog where they're either really funny or they actually go through insane lengths to explain, by the way, watch out, like, this is the new stuff that's in this version. You might want to stick to this version. So much thoughtfulness and a few developers. But the rest are just minor bug fixes. Minor bug fixes. Improvements. Speed improvements.

Bug fixes. All these releases. What bug are you fixing? Tell me. Maybe I had that bug. The issue number or something. Yeah. Give me some context. Yeah.

And especially for iOS stuff, so many little subtle bugs that you could make people happy if you just mentioned what bug you fixed. It seems so obvious, but people don't do it. So is there a semantic difference between changelog and release notes, or maybe just the audience? It seems like when I think of a changelog, I think of the audience being technically sound

and maybe even developers. When I think of release notes, maybe it's just in the app store. Obviously, you're speaking to your end users. Maybe it just depends on who your end user is. Right. I realized that while I was doing this project, as soon as I put it up, someone came up and said to me, hey, so you're

calling this a change log and there's actually a different thing called history or uh news and in the in the git or the new community there's apparently a differentiation between those two so there's one that's more release note oriented and i think that's the news yeah so it's the news text file that you leave in your repo. And that one's more generally like if you want to parse it really quickly. And the changelog, they contend, and I'm kind of not super happy about that.

They contend that the changelog is just, it's okay if it's just a git diff dump. And I think there's no value in that. If we use git and we can use git log, why would you ever... You can do the same thing on GitHub. You can do a compare between two tags or two specific release commits,

and you will see that diff. You will see those commit messages, and you can go through every single one. Sometimes there's just an angry developer going, ah, I faked this super annoying thing. There's no context. There's no semantics. It's, it's very strange to me. I liked your, um, you say, so the homepage for this project is keeping, or sorry, it's keep a changelog.com. So if you're listening live, you want to follow along. If you're listening, obviously this is a podcast, you are listening.

If you're hearing this, but keepachangelog.com. And one of the questions down there says, is there a standard – to Jared's question there, is there a standard changelog format? And your answer is sadly no, but you hope to make this particular one you're making as part of this project become the standard changelog file for all open source projects. And I would assume maybe others to follow along. And it's got this idea of added, deprecated, removed, fixed, which I think is really important because it kind of gives you a rhythm to follow, at least, you know? Yeah, and this is something that I noticed, that a lot of people just say what was added and say what was removed, but they don't say, okay, was something not deprecated? Because usually when you parse things, it's also

as important to you to know that nothing was deprecated in this version, and you can safely upgrade. Because if it's not mentioned, maybe it's not there, but maybe they forgot. And it happens a lot in open source projects because, you know, you get some, you merge a contribution, and you forget

that person didn't make a changelog commit, and boom, you're suddenly breaking all these installs from people. And it's just a lot of friction and pain that I think we could easily remove with a little bit of forethought. I love the dog you have in the background too. You warned us, but the dog is still there. He's going nuts. I don't think so. He's having fun right now. He's actually never done that. But I think he can sense that I'm talking. So he's like, okay, let me screw with him.

It's giving your side of the audio a little character, so to speak. Yes. So let me read your definition here of a changelog back at you. And then we can kind of discuss the difference between this and other things that may exist. You say that a changelog is a file which contains a curated, chronologically ordered list of notable changes for each version of an open source project. And so I'm guessing that, I'm reading the tea leaves here,

that you're emphasizing curation, chronologically ordered and notable as kind of the key differentiators between this and what might be a history file, which maybe is all the commit logs. Is that fair? That's very fair. And I think the difference is clear in the same sense.

So if you think of an API, a public-facing API, when you change things on the API, you want to make sure that everybody understands what they are. They don't not really the low level stuff that you changed, but the actual public API stuff. So the private API stuff is nice to know, it's good, but it's not as crucial for you to know. So this is basically the same differentiation. It's like, this is the for the outward world, not the people who work on the project, necessarily, the people who work on the project necessarily. The people who work on the project know that there were things added privately, that they did some groundwork for a new release, for instance, but that's not necessarily notable for the people using the software.

And I think that actually, we talked earlier about release notes for iOS apps or just Android apps. I feel like I wish open source developers would basically crank up the empathy on their open source end users the same way that iOS developers sometimes do with their paid customers. Because yes, people don't pay, but if you keep such a well-curated list

of all the changes, first of all, it encourages people to do the same. It makes it easier for people to jump in and contribute. Because, for instance, I think Hamill was an example. I was waiting for a feature in Hamill or a feature in Red Carpet, one of those things. And I was about to start working on it. And I thought, OK, so it's not listed in the readme.

I can't find it anywhere. And I went through the chain log real quick. And boom, there you go. Footnotes were added, I think't find it anywhere. And I went through the chain log real quick and boom, there you go. Footnotes were added, I think recently in red carpet. And I was super excited because for my blog, it's just little footnotes and you could do that very easily. And I didn't have to go any further. And of course you can improve your feature descriptions on your library, but it's also great for people to just jump in and see, wow. So yeah, when you jump in a project, you, you always assess how well maintained is this project?

What better way to see how well maintained a project is then show, you know what, every, every month, every week, every year, we have this, these incremental changes, and this is all the things we carefully change and add yeah absolutely i think man as a user of open source software and somebody who's written a lot of software over the years you know i used to get really excited for like every single project update and i was like oh i can't wait to just integrate you know upgrade and get this in there and and you kind of as you get scar tissue to the process of software development and realizing that your regression test suite is not as awesome as as you thought it was and there's still bugs you know affect you and trickle down i get to the point where i am very weary of upgrading uh dependency that's so sad. I know. But let me just say,

a solid change, like a release notes or a change log that actually provides me the information of here's the value in upgrading to our newest release, like high-level bullet points,

kind of what you're advocating for here, of like, here's why it's worth it for you. Here's the new stuff that is, you know, of value. Goes a long new stuff that is of value. It goes a long way. This is exactly that.

Okay, this is worth me actually going through the process of upgrading this dependency. Well, that process you talk about too, I think that to your point, that you say that you wish more software developers, more open source developers took some, I'm not sure what your exact words were, but I'll think of it like just making social, it's gotten harder and harder to take care of these staples, so to speak, like changelog, readme, history. All these files are like staples in software. And I feel like it's just more added overhead to deal with. It's a good point. And I think the word I used was empathy.

And it's a difficult thing because when you when you're drained you know when you've worked so hard and i know that a lot of people get a lot of flack uh on their issues and you know people come in and just crap all over their project even though they've worked for years and years to make it uh but i feel like in a way if you think of it uh as a preventive measure preventative preventive Preventive? I don't know. You can basically, okay, let me carpet bomb, in a way, this information to make sure that less misunderstanding and less confusion will happen. To me, if you keep a change log and you do that often and regularly, you're actually saving yourself the hassle

of having to deal with people who misunderstand or who are having upgrade issues. Basically, you're just saving yourself a lot of time. And it's hard to see, of course, because just writing down little things like that means that you have to take some time to reflect after a release or just as you're about to release. Or you have to find out like,

oh, what pull request did I merge in and did they put a changelog item, stuff like that. But if you do, then you're actually allowing your project to be more lightweight in a way. Because stuff is down and it's written down. You're not the central repository of, will this break my software? The file is. Yeah. software. The file is.

Well, let me just kind of... This might be hard for a listening audience, but kind of just go through your version on keepachangelog.com. Just kind of describe the format that you've laid out. This is sexy. Let's read the changelog together. I'm going to do it really slowly. So you have kind of... Should I slow the music down and everything?

Mm-hmm. Get some Barry White rolling put your put your bassy voice on jared markdown format i don't have a bassy voice i just said the word format i just said mark yeah markdown format is that everybody getting excited already everybody's excited so you're you're advocating for markdown format yep Yep. And so the first thing you have, okay, the title, we'll get past that. But for each changelog entry, you have a version number, kind of a well-formatted date, which you kind of, you have a section all about dates in here. And then you have four sections, added, things added, things deprecated, removed, and fixed. And in this example you give, your added has three bullet points, but they're hyphenated, the things added.

And then your deprecated, removed, and fixed are all empty, but you don't just leave them empty. You actually explicitly state nothing. Can you just go through the thought process behind this format and why you decided and think that this is, you know, I know you say it's not the truth at the bottom of the page, but is this something that you're advocating that people use? There's a ridiculous amount. So this is where we get really nerdy because every single thing you said, I had, like, thoughts going, okay, I have to explain this.

So the date format is a big deal because Brits are super this is great i hope you have brits listening i'm french so this is igniting a war and you know yet generations of war between us brits have the stupidest date format they put the number they say 8 april 2014 and they pronounce it april 8th that's it's just mind-boggling. So basically they have the wrong writing. So if they write it in an article, if you go to the Guardian and read an article in the Guardian, they often do that. Americans have an also stupid way to write dates where they put the month, and then they put the day, and then they put the year.

Just because, you know, why have a logical order ever? Yeah, I thought ours was surely the worst. Right. You're saying that the Brits is actually worse than ours. It is actually worse. So this is what I do. I basically, I anger people, and then I say, no, no, I hate, let's hate on these guys more.

You're just tearing us down over our date formats. Right. I'm just, you know, making making people, it's a strategy. Hear me out. I like it. So the last one is the slightly international date format, which to us is the MySQL database format, where you put the year, then the month, then the day.

Makes way more sense because, one, it's sortable easily. So if you have files in a folder and they're names with the 2014-05-31, you can sort that. They will never go out of whack when you're sorting it. So that's one reason. But the other reason is you can figure it out because it's different enough from the English and the American one that you can say, okay, this is clearly the year.

And I mean, why would the next thing be the day? Unless you really have the backwards American way of thinking. It's like you actually inverse that thinking. Let me just say that I use this format personally. Year, year, year, year, dash, month, month, dash, day, day. I use that on everything.

I could always just consider it the nerdy format. I don't know if it's like international format. Because only nerds would use this. People who who think about like oh it sorts naturally in a directory which i do think about and i use that on checks and i use it and people you know use that on checks yeah you know you put the day on the check and you use it i mean i just i like consistency so i'll just use the same like everywhere i'm not gonna i'm gonna do that well this this is my check context so i'm gonna switch to american date format now i'm just gonna use the same everywhere. I'm not going to... I'm going to do that now. Well, this is my check context, so I'm going to switch to American date format. No, I'm just going to use the nerdy version.

And people here in America, they get mad at me for this. They're like, what? What's up with your date format? And I'm like, it makes the most sense. Biggest to smallest. It's unambiguous. So I'm totally in with you

on your sensible date format. I just think we just use it even outside of changelogs like let's just get everywhere let's start a revolution so you see you have to make you have to make another website like single page website like this where you're talking about let's uh let i don't keep a date format i don't know what you want to call it but basically that the the thing that scares me and what you say is that i don't really i didn't realize being outside of well having grown up outside of the American culture mostly, I don't know what's super weird. I just know what doesn't make sense to me.

But there are things that I say or do that shock people and that surprise me because it's just not a big deal in Europe or in France. So anyway, so the date is one super important thing. The other part actually is it's like headings. So the first heading, and this is something I've been criticized for, and I'm completely okay discussing it because as you mentioned, it's not the truth. It's just an idea for a convention. We can agree or disagree.

We can improve it, be better. But the first heading, so like Markdown has pound signs for headings. So header one is changelog. So the title is changelog just because what if you discover this file and you have no idea what it is? If you're a beginner to open source and you jump into this text file that says changelog, what is this? Do you see changelog?

And then there's a subtitle was a little paragraph underneath that says all notable changes to this project will be documented in this file. Self-explanatory. I have context now i don't need to be a nerd like us to to understand that why is the did format like that now you know okay i can sort of this decipher what's this thing about and then i use header two header level two for every single version because uh well one of the reasons is that GitHub added to, I think, GitHub-flavored Markdown,

the auto-linking anchors on these headers. Yes. Which is great because that means you can automatically, if it's parsed as Markdown, you can link to the release by clicking on the little paragraph sign that shows up next to the anchor level 2. It's kind of hard to demonstrate. And finally, there's the third one, which is the individual grouped.

Why individual group? No, the groups of changes. So the added changes, deprecated changes and stuff like that. And the dashes are simply because now in marked, I think it's a GitHub flavor markdown format, but a dash makes an unordered list item so it just looks better well yeah it's marked down unanimously that they did the the star or the dash right you're right because so many people use that in email format and whatnot so the idea was to translate from like normal way of writing words to something you can actually mark up without

trying to which is a great idea. Yeah. Or I guess mark down. Right. Yeah, I didn't realize that the dash also did unorder list. I thought that was just the asterisk. Yeah, so I'm the guy on open source projects that actually goes and submits pull requests through Uri and me and then sneakily changes all the stars to dashes.

I'm that guy. Your PR is just nothing but stars to dashes. What's up with that change no I know I sneak it in with other things so people go alright sure I guess whatever do you ever get your PRs rejected and be like this was a great change except for the whole stars to dashes thing

you try to sneak in there so now that it's public it will happen but no it's never happened and actually my evil plan worked every single time alright let's pause the show for just a minute give a shout out to our sponsor CodeShip. CodeShip is a hosted continuous deployment service that just works. We've been working with CodeShip for quite a while now we really really enjoy not only the product they've built but the people behind it. You can easily set up continuous integration for your app today

in just a few steps. And CodeShip has great support for lots of languages, all the test frameworks, as well as notification services. They easily integrate with everything you can think of, GitHub, Bitbucket. You can deploy to cloud services like Heroku, AWS, Nojitsu, Google App Engine, or even your own service because that's the way you want to do it sometimes too. Setup only takes three minutes. It's so quick. It really is just so quick. Get started today with their free plan and make sure you use the code THECHANGELOGPODCAST.

That's really important. Use THECHANGELOGPODCAST. And when you do that, you can get 20% off for three months on any plan you choose. Head to codeship.io and tell them the changelog sent you. Another thing I like about this format, too, is that there's a debate in your GitHub issues for this, to some degree, at least, talking about what the format should be.

And I think there was some other sort of unusual format that you kind of bulked at, and I think it's a closed issue right now, but you might recall that one. Some sort of other um i don't even know what the file format was but it was something weird i think markdown reads well because you can read it as you would not marked up to html you know precisely but you can read it just like it would be without like reading html you know it's just easy to read on its own but at the same time if a if the parser is smart enough it can take that same format and like you said earlier put the anchor tags on certain headings and allow you to like deep leak within

the same document so it has a lot of added benefits regardless if it's plain text markdown or actual kind of like markdown. I don't know what you would call that. Parsed, I suppose. That would be the better word. HTMLize. No matter how you get the file, whether it's the dumb version text or the smart version parsed, you get the same user experience or at least a similar user experience. Right.

So it's portable basically. Yeah. same user experience or at least a similar user experience right so it's portable basically so the the idea is that you can you can have it on your local machine even if it's not you don't have a markdown power parser it'll look fine and then it'll look even better on github or on bit bucket or anywhere because they will parse it and you'll see it what i what i've is again against the the idea is just try to keep it as accessible as possible um and that kind of that i don't want to go talk about that right like i don't know if you guys want to talk about that right now but that stems from kind of what my original open source uh i don't know uh

what's the religious thing where you just go convert people um anyway evangelism evangelism my previous thing was uh shields and shields was about github metadata badges and the idea was again keep things accessible because there might be people who don't use your project who will see it and then just get turned off immediately because they don't know what it's about what version it's on and stuff like that so it's the same mindset basically just making things as accessible as possible. And the format you mentioned is org mode, which I didn't know about. Yes, that's fine.

I was like, so what was that? Did you dig into it more? A little bit. So basically, it's Emacs. In the Emacs community, they use org mode for stuff like this. So they use org mode for everything that I think is metadata about the open source project. I might be completely butchering this, but this contributor talked about it.

It's nice that the Emacs community has this, but again, org mode seems so obscure. I think there was some syntax issues with the way I think it could parse Markdown. But yeah, again, make a great case for it. What I'm trying to achieve is not to please everybody.

It's this idea, I guess, that I take from the Ruby community in a way, because I'm a Ruby developer, is to, it's great to have opinions, everybody. And I certainly have them. But right now we're in a state that's not good, I think. And I think first we should achieve a modicum of consensus, like just have a little bit of a convention on at least this basic format. And then we can evolve it if you want.

But let's have that first. So that way, at least every project you can think of, you can go and click on a changelog file and see what's in it. Sadly, of course, the naming is an issue. There's a lot of projects that don't have any changelog whatsoever, so something would be a huge step up, right? Right.

And so what I encourage listeners to do is basically what I've been starting to do in the last few months. So I've put this page up, and I've used this page as argument bullets to go inside of a project that I use. And that basically when I do an upgrade, there's a shock and I don't know why something doesn't work. And I say, okay, let's see the change log. If there's no change log, I'll say, okay, do you want me to make a change log for you?

This is what I offer. This is the format. Are you cool with that? And at least two, three or four or more actually people have been like yeah sure you can do it uh just send a pr and we'll make i think um uh set um one of the contributors for discourse uh really great uh british guy i can't remember his name but yeah if you go to discourse um they use something to mini profiler yeah profiler, which is a rack mini profiler. Right.

So this is really cool profiling thing that you can use in Ruby apps. Sam Safran. And his change log was strange because it was backwards. So the oldest changes was at the top, which is kind of counterintuitive. And the date format was a little strange because he's British. No, we can't judge, but yeah. So I started just basically – A little jab there.

Yeah. But he's, again, an amazing contributor. But because of his cultural background – It's that one thing, the date, you just can't like it because of that? Yeah. It's not just that. It was more stuff. So if you look at the history of that file, you see kind of what I'm trying to do.

First, it's like reorganize and use Markdown. And people get hung up about Markdown, but Markdown, as you said, is accessible. It's very portable, yeah. Right. You don't need to know Markdown to understand what Markdown's about. And then the chronological thing was the second change.

So basically, I'm going to use this as an example of a template for how you would improve an existing change log and or create a new one. I'm trying to create one for a Rails a gem called strong parameters, which is hugely important to anyone who's using older versions of Rails than the current one. And sadly, there's no, it's very hard to find out what was added to this stuff. And some of it

really is, again, crucial because if you don't know exactly the difference between version X and Y, then it's suddenly very frustrating. And I don't want that. I want to remove as much as I can as far as frustration. What are the other culprits of frustration? Like in your notes, or at least on the homepage

of Keep It Changed Law, you got dumping a diff.'ve got these kind of lazy ways to like do a change law but not do a change log that right sort of upsets everyone so what are what are some of the ones that like really get you angry so the the one thing if you ever do a change log uh having a section about added and removed is fine if If you ever change, you make a backward incompatible change and you don't put it in your change log, that should just be the only thing you put there. So really, if you hate change logs and you think I'm silly,

just put one line for every single time where you change your API and you bump it up. If you use semantic versioning, then I will bless you. You're the best person in the world. That's great. But some people don't understand semantic versioning. Some people think you follow it, but you don't really follow it, things like that. So if you're going to change your API, your public API so radically, just make a little line that says, okay, now this doesn't work. You have to use this. That's it. That's the only thing i'm asking so so again like a huge generator of heat and like rage on the on

the open source world is that just basically breaking the uh the api and you're like oh there's a new version of this thing let's upgrade and then you turn into adam you just get really sad and bitter about upgrading which is what happened happened to me this everything i've contributed for this basically is fueled by by mostly anger and yeah it's all fueled by anger so i take the anger and i try to turn into something positive because i was upgrading this old app and all this was happening over and over and over again as you said test suite green nope not working oh why that's why and you figure it out and that whole little kind of maybe as a listener listening back like four or five minutes you mentioned shields which Chad Whitaker has been on the um has been on the show before he's you know I saw y'all do a virtual high five whenever

that moved over to badges that was super cool um and so that's that's a cool project for just for one so just to make sure you know we think that's an awesome project and we haven't had you on the show i never really knew who did it i just knew that it was a cool thing and then now it's part of badges and i think there's a org behind it and they're all kind of collected to one org now on GitHub, which is good across the board because it's like the UN for badges, basically. Okay, I'm going to steal that because that's a really good description.

New tagline. I have a blog post that I wrote about this called An Open Source Rage Diamond and that's exactly what it's talking about. Shields is... I like that we went there because Shields is exactly the response called an open source rage diamond and that's exactly what it's talking about shields is the it's i like that we went there because shields is exactly the the the response to why is everybody doing it wrong so you could rant about it make a blog post first and be on hacker news and everybody hates and likes you i don't know or you can take the approach of get what what's the lowest amount of effort I can exert to fix this.

And to me, so I was originally a designer, which is weird, and graphic designer and then web designer. And so I have Photoshop skills. They're rusty as hell, but I have them. So it was like, okay, there's this Travis badge and this dependencies badge from, I think, Gemfury. No, Gemnasium. Then there's Code Climate badge at the time,

which was like a blue badge that just said Code Climate. And I was just mind-boggled by that. Because I didn't have any other additional info. No, just like, okay, so we're doing the forum. Well, it's not badges, it's marketing. Yeah, right. Which I can sort of understand you're trying to you know market your business but and then it's kind of like what the phpbb signature era you know like

let's put animated gifs in our readmes so that teachers are flashing super cool um that sounds pretty awesome to me no no no no stop it let's do it Let's get them into our changelogs. People have done that, though. It's kind of funny when you put one gif and it's just, okay. You see it at the bottom and it's really funny. One gif per release, maybe? Can we get that? I think you should make one gif

per release for the emotion the release is supposed to instill in people. There you go. Jared, that should be your thing. Release GIF. I'll open a pull request on your changelog. Oh crap, we're live. Somebody probably registered that website.

So basically, I just made a template. I just made a simple template. The idea of badges, of shields, is simple. So it's called Shields because of one of the best TV shows of all time, The Shield. And you should watch that, by the way. Just a side note. It's a great show. The idea is a key and a value.

Just like we know. It's just like JSON or any format that has a key and a value. The key is, what is it about? And then the value is, for an example, simple example, build, passing, or failing. Dependencies, up-to-date or not up- or not up to date gem version what is the

gem version it's just like uh the good climate we'd show i've actually talked to uh brian helmkamp from from code climate and a bunch of other people from other third-party vendors that did those badges and i said uh would you be would it be cool you have this gpa thing on code climate which is really cool why not put that on the badge instead of your name? And he was like, yeah, actually we wanted to do that, but we were super busy with our startup that, so now you know why they did that because it was just a stopgap.

So you end up like getting in touch with all these really great people who just meant to do well, but either didn't have the graphic skills to make a badge that looks exactly the same as I think the Travis badge was the first. So I made this thing and I talked to the Travis people and I talked to the Good Climate people and a bunch of other, Gemnasium was really cool too. And I said, okay, how about we make badges for you and they're all consistent and similar color tones and similar

font and the font is more legible so people don't have to squint. They're like, what is it, Gem version? And then we make sure that every time you put a badge on these, we just recommend people link to that thing you do instead of trying to use the badge as an ad platform. You provide value and then we link to you and people will see, oh, Gemnasium is really cool. Oh, Travis is awesome. And that took off like crazy.

People started using the original P&G version of those badges all over the place, even before we actually had figured out a sustainable way to make them. So it was just me and my friend Nick, Nick Acker, just making them manually or generating them manually for everybody, which ended up taking a lot of time. But a success story nonetheless. And eventually, so open source did its magic.

After a year, a few people created APIs. I think we had a Go API. We had a Node.js API. We had a Ruby API to generate them on the fly. And this is what shields.io is. If you go to shields.io, you'll see tons of examples of things you can just simply pass a URL to, and the URL will generate a badge for you, which is now used by a bunch of services. And what's even greater is that you can do that for your license. You can show easily what your license is, what your donations, how do you take donations for your open source projects if you do.

And finally, they're all SVGs. So they're scalable. They work great. You can zoom in. They're easy to update. So, yeah. So you're trying to bring bring up another a conversion convert conversion a convergence similar to that around change logs right that's kind of the idea like we can all just converge

on this one format we can all decide that change logs are important things that we need to try to do well so let's assume that you've talked me into that and I'm like, okay, I'm a developer. I want to keep a good change log. I'm down with this format, um, that he's proposed. There's still a few things that I think are difficult and maybe you can help navigate that. Um, the first one being, when do I, uh, add to my change log? Is it every release? Is it just, uh, minor releases? Is it patch releases? Is it just major releases? So that's question one is like, when do you make a change log entry? And then question two is,

you say it's a curated list of things. So how do I decide what's worth putting in there and what's just noise? So the first part is every single release. If you don't have something notable, you can say notable changes. This is something that I'm glad you asked because this is something I hadn't really answered yet

on the site, so I'll probably add that. So when should I do that? All the time. It's very unlikely that you're going to make a release or cut a release or push a release if you don't have any notable changes. It's extremely rare. There might be some bug fixes,

but even those bug fixes, you can say, okay, we had a few bug fixes about what? That's it. It just takes you just really quickly, quickly parsing through. If you're the release manager, or if you're the main contributor, the lead contributor, or something like that,

it takes just asking in your contribution. So there's a GitHub added support for contributing.md or contributing that you can add in your repo to say, this is what we want you to do when you contribute. So start here first. And they're linked to in every issue. If you start an issue, it's linked to. So as a maintainer, why not put

that in there and say, hey, if you're going to fix a bug, please make a changelog entry. And a bunch of open source projects do that. And then there you go. Every minor release now has a symbol, a changelog entry that says, okay, we fixed this bug. Nothing else was added. So you can be relaxed. We didn't screw up your thing in the background. The second part of your question was, can you remind me? Because I lost your second part. Deciding what goes in and what's not worthy of going in to the actual entry.

So I think we discussed it a little bit earlier. It's if this is something that people as end users will send you packages with poop inside, if they find out and you didn't do it, then it's such a simple check. Are you speaking from experience there? No, but I would do it. I like how you went there. If they send you hate mail, that's cool, but packages with poop in it, bad.

Imagine your GitHub profile, imagine your profile on open source projects had your address in it. Would you be cool with that? Well, that's another issue that might be really creepy. Yes, Chad would. But imagine that people could actually send you mail, physical mail,

and it could be dangerous because they could put poop in it. Would that happen with this release because you forgot to mention something? I think the poop test is a great test. I think your idea, though, of putting stuff in it that breaks it because I'm thinking of when I upgrade WordPress plugins for the site or different sites that are still in WordPress or whatever, whenever I've got to bump up that plugin, I mainly don't care about the new features they add. I mainly care if it's going to break WordPress because it's database-backed and I've got to keep this database back up. And if something does go crazy, I've got to do a re-import of the old database to fix things or something that gets crazy. So I've had plugins totally break a WordPress theme, and all i want to know is like you know what is it breaking what what bugs were fixed that might break my theme right regressions it's people are acting as if

bug fixes are just this holy thing that never ever create regressions on anything but if i know if i knew you fixed a bug in the language parser and suddenly I update and language parsing doesn't work for some thing, then I can tell, oh, okay, let me roll back. This is probably what happened. So again, you're lessening the frustration level and you're allowing people using your software who know it's open source so they know it comes without a warranty basically in a. To self-diagnose easier, more easily. Yeah. Release notes is a good word for it. I mean, they tend to be – I like the idea of the fact of being changelog, right? The changelog.md even, or just a plain old flat, no extension changelog file in there.

That's cool with me too, as long as that format stays the same, because that's, I think, what's been the way for so long. But they basically are release notes. It's a way for you to communicate to those using it about the notable things, as you mentioned before, the most important things. Yep. There's something that worries me with...

Well, it doesn't really worry me. So GitHub released something called Releases, and that was me with, well, it doesn't really worry me. So GitHub released something called releases. And that was about a year ago, I think. There's a blog post for it. And their idea was, let's be smart. So I think they were thinking really hard about how to improve that too, on their end. And releases is fueled partially by Git tags. I want to mention that because what I don't like about the way changelogs are made right now, and a lot of people don't like them either, is that you can't really base them off of releases. Or if you actually tag your releases, so you say, okay, this commit is the point at which this is version 1.0.

In that git tag, which contains, which is great, like a lot of people don't know, you could put a message on a Git tag. So if you do gittag-m, you could put a message. And not a lot of GUIs allow you to see those messages, which is kind of crappy. And I don't know if GitHub and other open source repositories allow you to see that.

But you could basically put those entries, the added, removed, deprecated stuff in those git tags. And that would be great, except nobody knows how to do that. So they've added support for automatically pulling, when you create a release, when you try to create a release on GitHub,

it will actually try to finally tell you what is the git tag? Do you have a git commit or a git tag we could use? And if you have a message on that git commit or the git tag, you have a git commit or a git tag we could use and if you have a message on that git commit or the git tag it will pull that and say do you want to use that as your release note and that's great except that it's very rare that people actually it's even more rare that that people keep up-to-date Git tags for every version they release than it is for them to even have a change log in the first place.

So it's a little like, I wish people, it's asking even more than I'm even asking from open source developers, it seems. It's time to pause the show just one more time for our friends at Rackspace. We've been working with Rackspace for quite a while. Love this hosting platform. They continue to dedicate themselves to support the open source and developer community with their developer discount. And now you can go make something awesome on them. You are the makers.

You're the people with the ideas. Along with me too, sure. Why not? But each day we get up thinking of new awesome things we could do, new ways to change the world, and they want to help you put your imagination and your skills to work. And Rackspace would like to give you something special just to say thank you. Sign up today for their developer discount,

and you're going to get $300 in free cloud services on your Rackspace cloud account. This discount applies to new products like their performance cloud servers as well as cloud queues. You're even eligible for early access to new features and products as they roll out. So make sure you sign up. $300, that's a lot of money. Make something awesome. Get started today. developer.rackspace.com slash devtrial.

I think we might be kind of talking around this issue that you have on the project. Why not use GitHub release notes? And you got a couple chimes in from GitHubbers, TechnoWeenie, Beekeepers. Yeah. And I almost feel like GitHub muddied the water, so to speak, by having this concept of releases. Yeah. which is why GitHub is blown up the way it has because they took what used to be hard to commit to a project or fork it or add to it and they made it so much more accessible socially why not do the same thing for this idea

of what a changelog is and represents for a project it's true but at the same time I've had conversations with them I don't work for GitHub and I just have a few people I know that work for GitHub and every time I talk to them, it's a really good conversation,

and I can tell they care. I can tell they're trying to do, let's say, contributing that contributing file, for instance, a good example of what you're saying. Why not just parse that changelog file and then display it somehow in the Open Source Projects dashboard, like in a sidebar or, don't know something but in that way it would be lower as you said easier to do and it

wouldn't add one more entry point for for releases but i'm thinking maybe they have a point in the releases i think something that i've noticed gith GitHub doing is just trying to make Git more accessible in general for every possible way. And releases is kind of saying, okay, well, you have tags, but tags don't really mean anything to most people. It's just like, what is a tag? It could be a lot of things.

A release is a tag that has a specific kind of meaning because you could have tags that just say experimental, right? Or like Rails 4 or whatever. You have this little branch that you tag that. That's not really a tag, actually. That's confusing. That's just a branch called that. But in this instance, I think you could see tags.

Yeah, if you go to releases on GitHub, you can see all the tags that a project has. And there's not a lot of metadata there. There's not a lot of context. They were basically trying to say, okay, we know that Rails and jQuery and all these projects have tags in their releases and stuff like that.

What if we just use that? So I guess they had a way to do that. And I think it's really interesting how they make it, the flow of creating a new release as an open source maintainer. Just, okay, you pick a tag version or you make a tag version or you make a tag version and

you target a branch or a commit yeah recent commit you put a title on it which is kind of for me because way okay so what's the title it's just uh a new day uh hope we already know naming's hard so right so you're you're like making it harder on them uh but at the same time what's more that overhead that that prevents you from doing in the first place right so you're you're like making it harder on them uh but at the same time what's more that overhead that that prevents you from doing in the first place right so this is why conventions are useful because it means less thinking and more you could so what i like about their approach is the git tag stuff i think if we can down the line if tools if git tools or git itself makes it easier for this is more like a three-year

vision than right a in six months i can fix this if they made it easier to manage and deal with tags then it would be very simple for us to generate a change log on the fly based on the git tags and that would be to me the best possible paradigm because now instead of managing this file you could have any service parse your Git tags and generate a change log on their own and display it the way they want. And it would be portable by virtue of being in your Git history. Yeah, the only time it would be lost

is if someone downloaded a bundle of your files or something. Right. Without the Git hidden directory. Let's say you could have a little generator, whatever your make tool is to make your release, you could have it just actually dump an actual changelog file, and that would be really cool.

We've got to find a way. And I'm glad you're on this mission because you seem very passionate about it, plus I don't think we got this in the show, but you're into linguistics, so you seem like you've got some passion around the right words to say in the right ways. That's why you use the word notable, not just important or something like that.

I think notable is an even more clarifying word to what you should put in your change log. To close the show out, though, we always ask a couple of cool questions, which we tend to get some neat answers to, so we're hoping that you deliver here as well. But Jared and I both and the listeners are also wondering, too, but who is your programming hero? See, I've thought a lot about this question because you sent me that a little earlier and um i think it's not really so much programming as just the way to think of

what's the smallest thing i can do that can have the greatest impact right now my hero is aaron swartz uh just because uh through him there's so much great change and important chain has been affected uh and i hope i'm using affected right because if I'm calling myself a linguist, I guess that would be terrible. But he's – if you guys know, he sadly killed himself I think last year while he was being investigated by the FBI and through basically just this assorted affair of just trying to release information that the public owns and should have access to.

So research, basically, to all the public research that is funded by the American government and you, your tax dollars. Being French, it's weird for me to care about this, but there's even less care in France for that. So to me, people like him, I don't want martyrs. I want people like him who just passionately try to make things right and don't accept that because it's the way it is, then it should stay the way it is. Like when people say, oh, it's the law, it doesn't mean you have to break it, but that doesn't mean you can't change it.

If there's a bad law or Congress is trying to make the internet less good, then maybe you should do something about it and could start with a tiny little thing. If you help bolster the open source community by making an open source project that allows for people to seek campaign contributions, or I have a friend called Tim Faust, and he's this crazy, super Excel genius guy,

and he's currently parsing through the Texas, I think, gubernatorial, or one of those, like basically the campaign spending on each parties to see what parties waste money on, which is super important information. So it's basically civic hacking type stuff. And yeah, people like that inspire me a lot. Beyond technical, it's just like,

okay, so why are you doing this? What is your purpose? Because your technical prowess is great. And he created RSS. I think it's nice when you marry those two, right? The socially aware to the technically capable, you know? Right. And that's...

A lot of people really, you know, were behind his... I mean, he was a big proponent of, like, the free internet and the freedom in internet of this, you know, of our data, data security, data portability. So I think he kind of stood for a lot of that, and I can totally see why you feel that way. Yeah.

So I recommend anybody listening to this, try to get a copy or see The Internet's Own Boy, which is a documentary that was made about him. And it's very sad. You will cry. There's no way you can come out of this like, yay. But it might actually spark some, you know uh care for you and and just it doesn't have to be as epic or as dangerous as some of these things are it could be something simple like this so yeah that's my that's my hero we'll put uh we'll put a link out to Aaron and then we also linked out to the video you're talking about it was was a teaser. It was an interview of him as a teaser to the documentary. We linked that out in the Change Law Week,

their weekly email that we were sending regularly. We took a hiatus and we're relaunching it. So if you're sending us hate mail, I'm going to keep ignoring it for the next few weeks and then I'll let you know what's going to happen with it. But we linked out to that video because, like you said, it's pretty powerful. And I think it's important to just be mindful of at least what his life represented and then what internet freedom is for us. Because I think he really – he was the cheerleader, so to speak, for that. Is it the SOPA video? I believe so, yeah. It was – I think he was at a conference and he was being interviewed and it was sort of like happenstance. But the questions and the interview I think was just – I can't recall the scenario, but it was a trailer for that documentary you mentioned.

Yeah, it's basically the story of how they destroy SOPA by just working hard and he just basically ranted about what's in a good way obviously sometimes the word rant can be used in a bad way but in a good way he was ranting about his beliefs on why we should care about this and why it's important and sometimes people just are oblivious to things and they just don't see and then you got the one outlier that's like whoa hang on a second there's

bright spots here no one's paying attention to and here's what they mean for us 10 or 5 years from now and I think that's a really important you know internet freedom is is important to give you a quick uh person to admire that is sadly not dead that hopefully not dead uh larry lessig that's weird that was backwards let me just we got a linguist on the call that said he's... I'm just kidding. So, Lawrence Lessig was a mentor of Aaron Swartz, and he's currently running a campaign called May 5th, or I forget the total name of it, but it's basically he wants to create a super PAC to stop

and basically disable super PACs. So, super PACs being big political action committees that can raise tons of money, even though basically skirting campaign contribution laws in the US, which is also a problem anywhere else. Like there's tons of issues with campaign contribution. Basically, if you have money, you can buy enough stuff so that you can get your friends elected to do things like,

say, internet neutrality. Not necessarily that important. So things like that. He's a great example of the kind of spirit of Tim Berners-Lee, Aaron Swartz, Lawrence Lessig. Boom. I got three for you. Well, those are

good heroes. We'll put links in the show. So for those of you who those may be new names for you, a couple of them are for me, at least one of them. The last one you mentioned.. We'll put links in the show notes. So for those of you, those may be new names for you. A couple of them are for me, at least one of them, the last one you mentioned. So I'll put notes in the show notes for that. Another question I'd like to ask is what's a call to arms? For this project, we talked quite a bit about the importance of keeping a change log and what that means and what you put in there and what you don't put in there in the right format and the markdown and all these different notes of this but you know what is the overarching call to arms right now for keep a change log if you're gonna make a change keep it i was that

just came to me as you were talking so if you're going to try to make things better because open source developers generally kind of have this urge to some of them change the world i'm like okay well what if you make it a little better first before you want to change it uh because change the world it doesn't have a clear angle it's like what are you changing it to is it bad or is it good so what if you fix a little problem and then another and then another and when when you do that, remember that other people can help you and that you're not this island. So I think shields for me was the best example of that. I was this island. I was, it was one in the morning with like 11 PM and I was pissed off. And I thought this, I was the only person who cared and I wasn't. And because I documented my project, because I spoke

about it, because I talked about it with friends, people came in and they, they multiplied my, you know, the, the lever effect, basically that it's just, I was this one guy at the end of a huge stick in a boulder. And then a bunch of people showed up and we just like lifted this gigantic boulder out of nowhere. And this is why I'm so excited about open source in general. It's just like source in general if you care if you pay attention to the details that you think maybe won't matter then people will come and help you and make what you're trying to do even more powerful and impactful so I hope people can take that out of that awesome

our next question, our last question if you weren't doing what you're doing now which is working at code school and podcasting and your open source contributions, if you weren't doing all that, what would you be doing? Photography. So I started, I sold my camera when I was getting into programming a lot because I had so much stuff to learn and so much money to spend elsewhere. I sold all my rigs and I had, I've been taking photos since my mom, I think, had a camera when I had so much stuff to learn and so much money to spend elsewhere that I sold all my rigs and I had I've been taking photos since my mom I think had a camera when I was a kid and I

and I've always loved taking pictures of landscapes and stuff like that but recently I purchased a Sony RX1R which has blown my mind it's a full frame small format non interchangeable lens camera.

So you can't pop it off and put another lens in, but it's a 35 millimeter great camera, full frame and everything. And I've started doing a thing that I've been terrible at all my life is trying to take pictures of people. So trying to take portraits of people and try to capture not their good angle, not their sexy looks, not their, I don't know. But trying to capture their essence and try to see,

if I show this picture to somebody else, if I put it on Facebook, for instance, will the people who know this person say, this is so you? And it's a completely different kind of creativity thing that you have to do in your head to figure that out because you have to talk to people. And I think that's actually really helpful for open source and we're just programming in general because we tend to do that in a slightly in a vacuum that having to uh either either trick people into trusting you or like having people trust you enough to get close to them and take

a picture of them and have them be genuine to you that's it's really really exciting i've been doing that so i've had this i think instagram thing i hope i wish instagram had public okay big rant if anybody who knows anybody at instagram okay they have tags they have these like hashtags and none of them are available on the internet you can see my profile on instagram.com slash me and you'll see them and you can find them, but you can't have a hard like permalink to, and it's not public data.

I know they own it, but please someone on Instagram make those tags public because sure there's some really crappy ones, but there's something great called People of Orlando. So I'm, that Kutzko's in Orlando and I used to live in Orlando and there's so many great people,

so much crap from being in Florida, of course, but there's so many great people and there's this photographer called Patrick Chin that started this thing where he basically goes up to people

and asks them about their life, their story, and then takes a picture and he tells that story on Instagram, which I think, I think a really cool thing that a lot of people do in other cities, but they're strangers.

He's never met them, and they all have great stories. So that's what I'm trying to do, basically. I'm just checking out their API docs while you're talking, because I'm thinking, man, you've got to be able to get them somehow. And there's definitely tag endpoints

in the Instagram API, so someone could build this. But you have to be authed. So I think Staticram, or whatever Staticram is now called, you can see tags, but you have to be authenticated as yourself. It's not a public endpoint, I think. That might be the problem. Anytime I get interested in something new, too.

So let me give you a half a second, I guess my half a minute rant. Like for a bit there, I was like really into learning about drones, right? So you got the Phantom 2 and you got several others. And it's really easy to kind of dig deep into what's the pulse of something going on visually and even like I guess the 10-second video they offer by just kind of browsing tags on Instagram. You know, droning, Phantom 2, pick your name. Like even if you're somebody who's an audio geek researching a new mic, you can go on there and see like bourbons if you're into bourbon, mics if you're into mics. And just kind of like look at the tags and get a snapshot of what the community around that interest is doing, saying, using, how it looks in their environment. I make product decisions sometimes based on what I see people using. I mean, I'm a foodie.

I go to restaurants, and I do that all the time. I go to the restaurant's Instagram, or I look at their tag, like whatever tag you can find for that restaurant, and I look at the food, and I see how good their presentation is, and I'm like, hmm, I'll go there, because Yelp sucks at that. Their photos are terrible. Yeah. The last question we asked, we do have kind of a – not so much a hard stop.

We just try to keep it to a certain range here so we don't lose people and people don't listen anyways if it's too long, is what would you be doing if you weren't doing what you do? So I guess we really didn't learn much. Adam, I already asked that one, man. Did I miss that? Yeah. Because you do photography. Yeah, yeah. So we just talked about it.

That's how we got onto that topic. Oh, my lord. I stood away for just a quick second and asked Jared to take over, and I totally missed it. So since you're listening live, you'll get this. The people who listen on the podcast will not get that. I will keep my comments to myself and just roll on out. Leave it in. Oh, that's awesome.

Well, you know, it was – in any case, it was a good show. Just roll on out. Leave it in. That's awesome. Well, you know, it was, in any case, it was a good show. I think this is an important topic, so I want to thank you for doing this on the show today. It was a pleasure. Let us know however we can help. You know, we obviously like to keep a change log on our own, so we're definitely into this. You're not fighting the fight alone. To trail off the call, I want to thank three of our sponsors,

Toptile, CodeShip, and Rackspace for helping make this show possible. That's it for this week. We'll be back next week. I think we've got... Justin Searles with Lyman. Yes, yes. I love that guy.

That's actually who you were referencing or who actually put the... Which one was it? He opened the issue about using GitHub's release notes. That's right, yeah. And he uses it for linemen. We'll probably extend this conversation a little bit there just because.

That's it for this week. Let's everybody say goodbye. See ya. Goodbye. you