Herald: Changelogs People Actually Read

Welcome back to another episode of the not brothers podcast. Today's episode is going to be a little bit different. We're going to be focusing on a specific area that we as technologists have explored and found a gap in the marketplace. And so in that gap in the marketplace, we felt compelled to create a product that solved our own needs, but also have gotten to a point where we're ready to make it available for others to use and solve the same pain points that we found. And that product is called Herald.

Ryan, why don't you start by giving a short explanation of what Herald is and then kind of go into why we built it. That'll kind of lead us down the path of what exists in the marketplace and what gaps, what gaps you specifically found.

Yeah, Herald is a change log management and authorship platform that really just seeks to solve the problem of like, keeping changelogs up to date and just producing changelogs. One of the things that I found, especially now with sort of the volume and speed at which things are moving and looking at an organization like ours where we've always built software for ourselves and for our clients.

we're building more and pumping out more features and things than we have historically. It's kind of created this problem where documentation and changelogs have always been not fun to write. It's nobody's favorite task. They get skipped often. usually when you could get away with producing changelogs once a week or once a month, maybe that was fine. It doesn't really work.

anymore. The other thing that we ran into was not only changelogs for the purposes of kind of the engineering side of things, it was changelogs for the user side of things. were shipping features and shipping fixes and have no way to let users of our tools know that those things exist.

So we were constantly finding people who were like, you know, well, I wish I could do this. like, we shipped that feature like two weeks ago. And they had no idea. just never, never noticed that it existed or whatever. you know, you would think certainly something exists to fill this space. And there are other tools that sort of do similar things, but I couldn't find one.

All the ones that I found were either too focused on only the consumer side and didn't care about the connection sort of with the code and where it comes from, or were just very clunky and overbuilt and overthought. And what I wanted is something that helps me in my normal workflows to produce the changelogs that I would want to read.

where they're straightforward, they're to the point, they have proper references to who did what, where that code happened, if there's a commit or a PR to point back to. But also allows for you to highlight and go deeper on some things. There are certain bug fixes and features that they're just a simple thing. We fixed this bug, we added this small feature, but then there are other ones that are big. We just added.

an AI agent called Nova to our other product called Nebula. That's a big deal and requires a little more than just a bullet point that says, know, hey, we Nova. We need to provide screenshots and how it works and, you know, go a little bit deeper on that. So allows for that ability while also, you know, increasing discoverability by users of the application because we can.

We have little widget that goes inside of the application. So anytime we ship new features, they can see that there. It also allows them to easily sign up for email notifications, give us a nice way to review those changelogs online, and synchronize and push all those to GitHub. So we kind of have this trifecta of ways that that information gets disseminated, while also making it incredibly easy to draft that because...

as we're shipping and moving through things, tries we might be super organized and diligent, somebody's still gotta go back through that shit. And sometimes pull requests aren't named super well, sometimes your commits are a little opaque, so you can't just pluck those out. And this is like the thing that AI was built to do, right? Is take a massive amount of inputs and data and sort of pull out the...

the trends and the commonalities. And that's exactly what we're using it to do. So you can do it manually and just say like, I wanna add this pull request and make it a feature. I wanna add this pull request and make it a bug. I wanna add this commit. Or you can just YOLO mode and let the AI agent scrub through sort of the commit history and the pull request history and come up with what it thinks.

and in sort of doing some of the tests and things over time and testing it even on some public repositories that are pretty large, it's pretty accurate and at least gets 90 % of the way, if not 100%, depending on sort of the gap in time that you're analyzing. And then at least takes away the majority of time that you would normally spend kind of picking through all of this shit. Now you can spend that time.

describing and writing content for the feature items is kind of how I look at it, right? I don't need to go scrub and pick out all of these 300 bugs that we just squashed and little minor features that we added. I can spend all of the time I would have spent doing that and trying to keep that up to date on describing some bigger features and drawing attention to those.

Yeah, I think one of the one of the advantages of what Herald does differently than what other products that seek to solve similar problems in the marketplace does is it it moves the drafter from being a creator of that release or of that of that change log to being an editor of the change log and it's two way sync right so you may still want to publish things to get hub that's fine that's totally cool and you and if you want that.

information to be two-way synced from Herald and GitHub, you can have exactly the same information that you're publishing in Herald that appears in a little widget created and drafted by AI, which you then become the editor of and, you know, mark featured releases and add videos and add photos and make it interactive and do all those things. And then you can push the other way to GitHub so that everything stays in sync and so that you don't have to do double entry. You don't have to duplicate effort.

on the other end, one the unique features that I think Herald does very differently than most others in the market.

Yeah, I mean, that's my biggest thing, right? I hate doing double and triple work. So again, I built the system for me, right? The challenge that I have is I have a number of products that internally I'm responsible for. I even have side projects, like some of the Diomarchi projects that I work on that I've got to produce release notes for.

it can be difficult on occasion to remember when you're working on something over the course of a month and it's not your primary thing. You're like, well, what the fuck did we actually do? And so it's been great being able to use this tool, but I don't want to have to publish it here, then go over here, tag a release, because I do still want those things to be in GitHub, both for our internal projects and external.

So that's where the idea of just sort syncing that stuff through. So the moment that we create a release, you create a release in Herald, you publish the release, it creates the tag in GitHub for you and pushes the release notes to GitHub that mirror the release notes that are in Herald and just keeps all that stuff in sync so that you can draft it in Herald. It'll push the drafts over as well if you want it to.

And you can kind of keep that draft updated over time. And then when you're ready to publish, you just publish it. And that's been a really nice workflow. We've also got some really cool features in there for categorization. within the default is features, bugs, improvements. I forget the other couple of categories that we have. But that's sort of the categories that tries.

When it looks at all of your commits and pull requests, it's trying to put them in one of those buckets and say, this is a feature, this is an improvement, this is a bug. And that also sort of tunes what it's looking for in terms of the, as it scrubs through the code. Those are also manageable. So the prompt.

that gets fed into the AI agent is available there and is tweakable. So when we think about different types of projects, maybe you have a project where you have a certain category of items that you typically look for. You can create that category and provide the description of what it means for that, right? If you're like maintenance items or something like if you wanted to have maintenance and it's like, hey, maintenance items are

minor revisions to library versions, cleanup items, whatever it is, however you would describe, whatever maintenance would be reflective of. And then that just helps the AI as it looks at things and tries to scrub them out, it'll pull maintenance items and it'll put them in that bucket for you.

So one of the things that I think is also different and unique is that the Herald allows for usage of public and private GitHub repositories, which most other feature sets or tools in this category do not. It's one or the other. It also provides for nestable projects. So let's say you have...

a couple of different gate repos that live underneath one primary project category. You can have them live separately, but then you can see it all independently, I'm sorry, together at a summarization level of how the releases have worked or how the projects have worked together. And so then an end user doesn't have to see the individual units or individual projects. They see the aggregate of what happened across all those different things while the details are managed independently. So those are, those are some really like quality of life features that don't exist in most other.

tool changelogs like it that you Ryan kind of saw as a, an opportunity just to make your own life easier. And now we can make that available for other folks to make their life easier as well.

Yeah, the nested projects was an interesting one. We were kind of thinking of it like, know, monorepos are pretty popular. And within a monorepo, the release kind of follows that repo. So it didn't make sense to try to create multiple sets of changelogs for a repo, but there are instances.

where you do have sort of a grouping of things, right? We have projects where maybe there's two different, two or three repos that are related to the same grouping of work. So we just wanna keep track of what's going on with that. know, one of them for me that wound up being a pretty hand in glove situation is a Marchie. Because we have, you know, we have the Marchie project, we've got a Marchie ISO, we've got the Marchie zish, Marchie zish fish, you know, there's all of these sort of like sub.

products, and those are all separate repositories. So if you wanted to just kind of follow all of them in one go, you can just follow sort of the parent project, and then everything else has their own releases that happen, and you can kind of see all of those together, but also see them separately. So it allows you to kind of roll all that stuff up, look at the parent change log with all of the subs.

But then also if you just want to drill into like, what changes happened to this package, you can kind of drill in and just filter down to that when you're on the actual changelog page itself.

Another area that I thought was interesting that you thought to build into this was scheduled releases. So it's not just at the time of publish or at the time that you push the publish button, you can actually schedule when you want these things to go out as opposed to being live just all in one go.

Yeah, I mean, I'm sure somebody will use that. don't. know, whatever. It was an easy enough feature to add, so we just kind of did it while we're in there. if you're the type of person that like you want to schedule your releases to happen on a certain day and time, you can do that. I generally don't, right? Like when it's done, it's done. I should publish. But I'm sure somebody will find value in that.

So talk about how to get started with something like Herald and what your experience has been like working with other similar changelog tools, whether they were easy to use, difficult to use. How did you structure getting started with Herald that may be unique or maybe it's the same as other tools work?

I mean, most of the other tools that I had dealt with or researched really just did the most horrifying thing, which is just drop you off with a blank canvas. The most exciting and terrifying thing in the world is a blank sheet of paper. So we don't necessarily do that. It is, at least today, the key integration is around GitHub.

where the ideal path is you sign up, you connect your repository to the project. So you connect your GitHub repo to whatever the project is.

And then you can start from there. You can start importing items that you want to populate with. You can draft a release, and you can start importing items to that release either manually or using the AI-driven approach. So truthfully, you could go from sign up to a drafted set of changelogs in about 30 seconds.

because you just have to connect the repo, authorize, do the off dance. And then you could go draft a release, hit my favorite button, which is the yellow button, and just say everything since the last release. And it'll take the time period from whatever your latest release was on GitHub. And now it will analyze everything in that gap.

to sort of produce whatever this release would be. And then nine times out of 10, you could probably just hit publish from that. Unless there's something that's worth expounding upon, or I haven't actually had anything that has just gotten wrong. If anything, I've found that the way that we have it tuned, at least today, it's a little bit more probably conservative, if anything. So it may leave.

It may leave something that's a little nuanced out rather than adding in extra stuff that just doesn't make any sense.

So with the setup, there's also the ability to create the widget inside your application. can choose not to do that, but within the setup of that GitHub repo, there's also a little script that you can copy, paste it into your code base, and then a widget will show up that says what's new in the bottom right-hand corner. And that widget is, and the entirety of the widget, not just the button, even the text copy and the formatting and all those different pieces.

background colors, text colors, font choices, are all customizable within the system so that you can make sure that not just the application itself, but even the changelogs are on brand within the application and within any email distributions that you send out. When they click through the email and see the web version, it also is branded based on how you've configured that widget.

Yeah, I mean, that was a key piece of the kind of the other end, right? So the first part is like, how do we make it possible to create changelogs based on the actual code that's been changed and make that a really just fluid and easy to do process, right? If we can lower the barrier there.

we increase the probability that it just gets done. Otherwise, the more friction and more difficult it is to produce the changelogs, the higher likelihood that they just don't get produced in the first place. Once we have them, the second side of that is how do we get discoverability? So pushing those to the GitHub repo is one way that you can find and review the changelogs. Having those changelogs available at

A URL is a second way. if you bookmark that or whatever, signing up for email notifications, you can get notified when there's a new changelog published. That's another way. But then what I thought was really valuable was just being able to pull that directly inside of an application. And we do that through, obviously, a little JavaScript widget.

and being able to plop that in there and say, like, you know, every time you log in, be able to see if there's something new that's been published, that little widget can just kind of have like a little one next to it. You click it and you can re review whatever it is that was published. It's helped a ton for our team as we ship things on different products to just know like, hey, you know, we sort of ninjas shipped a bunch of stuff on Friday and people show up on Monday and they're already starting to use it because we've let them know.

Yeah. And you know, there's, lots of ways you can notify people of those changes to your point, right? So if it's an internal application, maybe it's a base camp message or something like that. What we've found is that this, because it lives in the application itself is the most discoverable, least intrusive way to let people know what's going on. They, either care about what it is or you don't. And if you don't care, you can just exit out and it goes away. If you do care, then you can dig as deep as you want all the way down to finding the exact commit within GitHub itself with all the commit notes.

that are related to that.

The other thing it allows with putting it the application, depending, we have some applications that there are sort of groups of people where we have internal users and client users. And maybe there are features that are valuable to our internal users, but the client users are never going to care.

So we don't really want to bother them with those items and those release notes because they may not even understand them. So another feature that's been built in is you can sort of create these groups of people and cast your users, put your users in those groups. And then within the widget, using just like sort of some JWT auth.

you can pass who your user is. So if it's an authenticated application, you can say, hey, this user is an internal user when you're passing that embed code. And then the changelogs that come back, and even if they click on it and go to the website, the changelogs that they see will be just sort of the changelogs that have been allocated for that person. So you can, on a feature by feature basis within a specific change log,

or within a specific release, you can tag those items as visible to the different subdivided groups that you might have. And that was just kind of another way of increasing that discoverability by all users, but also maintaining some flexibility for situations where maybe you don't want everybody to get the same thing.

You can think about how powerful that can be. So in our example, we're talking about internal users versus client users. And that's one of many use cases. Another could be beta users, people that have signed up to be part of beta release cycles. And the average user doesn't need to see those things, but beta users do. And so there's kind of an endless use case for the segmentation that's built there. Really powerful.

So, go ahead.

Yeah, I mean.

The tool itself is not incredibly complex and it's know, entire, like this is not earth shattering technology. But I think it's done in a way that is a little bit different than I've seen it done elsewhere. And I think it's something that adds value.

in just the right capacity. So that as a user responsible for maintaining software, as a user or as a developer who's responsible for producing release notes or wants to keep their users up to date, gives you the tools to be able to do that, but in a non-intrusive fashion. So everybody gets the best of both worlds.

Yeah. So the three user types that this has really made for is the developer that actually wrote all the things, the developer that may be responsible for, or whoever's responsible for creating the changelogs, because it may not be the developer, it may be somebody completely different. And then the end user, however you define that as a segmentation and the user experience and the navigability and the simplicity of how it works.

makes it super easy to understand, super easy to get in and figure out, super easy to connect and write your first change log, and hopefully really easy to rinse and repeat that cycle as part of a normal workflow for each of those user types.

Yeah, no, think it's a useful tool. I'm sure we'll change it over time. I'm excited to see what other people think of it. And if other people find the same value that we've found, we've published dozens of actual release notes and hundreds of test ones, both for our projects and then also

just sort of scouring, like I think I turned it loose on open clause code base just to see, basically trying to see like how far you could push it before it would just absolutely choke. And it stood up pretty well, especially after some tuning based on those.

Yeah, pretty cool. On the overall website, we have an interactive experience that kind of shows you what it looks like on a couple of our internal projects, as well as some pretty complex and robust external open source applications, just so you can kind of see how the experience works.

So any parting words of wisdom?

No, try Herald. Let us know what you think.

Herald, let us know. Until next time.

time.