Background: Why Hew?

Some people are obsessed with birdwatching, or coffee, or fixing up old cars. My obsession has been changelogs—look, I never said I was an interesting person.

Years and years ago (while my wife slept off morning sickness with our first kid) I built a toy project that scraped and parsed changelogs from hundreds of open source projects. I painstakingly reviewed the results of my parsing heuristics to try and extract actionable information from changelogs authored in human-readable prose rather than structured data.

You and I know that years-and-years-ago me was on a fool's errand, but he didn't know that. Even though my efforts mostly fizzled out, I came way with a few lesson-scars:

• Inferring structure suitable for machines from the written word is really hard to do and even harder to fully generalize.
• There is no standard for changelogs or release notes—not even an above-50% pattern people follow.
• We could do really amazing things if the story was different.

That last bullet point stuck with me. Imagine if every dependency in your lockfile could easily answer a query like, "what pending performance enhancements am I currently missing out on?" or "is that annoying regression fixed yet?". Hew doesn't give us that kind of ambrosia (yet???) but you can see the golden path that leads to it: you need structure. You need standardization. You need total and complete mind control over every developer to do exactly what you say to make your idealized dreams a reality (again, Hew has not solved that problem. yet???)

An xkcd just popped into your head, and I apologize for that. Is the hypothetical solution another standard? Yes. But it's not one that forces you with compliance vinegar, it's after you with feature honey.

Proto-Hew

I was a startup engineer at Bowtie doing a little bit of everything: operations, CI/CD, and importantly, userdocs. The sleep-deprived startup employees in the audience know that there is not enough time to do everything you need to do when everything is urgent all the time.

Even on a small team, writing release notes means aggregating all the knowledge about pending features and then synthesizing it into a form that users and customers care about. This isn't just writing a CHANGELOG.md file, either: customers like to be notified about new releases, they want important changes front and center in documentation, and those are good things to want.

The traditional way to do this is for the documentation owner to:

• Touch base with every human frequently
• Get a brain dump from them including what impactful changes end users should know about
• Turn this into a pending release note
• Do all of this again when the time arrives for a release candidate or production release

That all sucks so bad! It breaks engineering focus, requires copy/pasting into different channels (we had a release feed in addition to a documentation site), the list goes on and on.

So, I exercised unrighteous dominion and forced everybody authoring code to write a markdown file describing anything relevant to end users in the same branch as their work. I reasoned that all of the rest could be inferred from git history: which tags each descriptive change belongs to, whether to categorize it into a "Fixes" or "Features" section based on the parent directory, that sort of thing.

I built code to do exactly that. Then we sat on it for, like, literally two or three years while the logic firmed up. I fixed bugs that arose from squashing, or cherry-picking, or renaming files in git history. Eventually the bugs stopped happening so regularly, but most importantly:

I spent literally zero time maintaining a CHANGELOG.md file, or curating the release notes, or doing drudgery work like "whoops, I forgot to add an 'Unreleased' section again." It did what I wanted! And I really wanted to use this system outside of work! Sounds like it's time for unpaid OSS labor, baby!

Hew, Hew, Baby

Since I'm the benevolent dictator at this moment in time, I can do what I want, so I didn't just write a formal specification, I wrote an informal specificaion, too. It's actually readable by a person if you want to know how it works. Imagine!

The first internal implementation was in Python, so I generalized it and put the repository here. Eventually I (or you?) will implement the specification for other ecosystems.

For the software engineers in the audience, here are the parts that I personally find very appealing about Hew:

• Treating changelogs like "source" means your release notes live in one place to compile and deliver artifacts wherever you want. I really like this idea.
• Fluid document formatting is a built-in concept: at my day job, we transform the raw changelogs into many different forms with Pandoc and use it to great effect. Your changelog authors can write their documentation in any form they like!
• Never think about what features shipped in what version. Hew knows! It's already in your version control history!

The entire project is fine-tuned to facilitate collaboration. That's why I burned so many brain cells writing a formal specification, examples, and tests for you.

Ships in the Night

So here you are skeptically reading about a new FOSS project, and here I am trying to explain it.

The home page hits the selling points. Here's what I'd add on top of that:

Software engineering is belabored by paper cuts. Your containers are broken. Upstream hasn't released your fix yet. And you have to maintain a markdown file by hand describing software changes for users. That's a tractable problem I've thought a lot about! I think a specification-based (i.e., no lock-in and cross-language) solution can automate away that problem, and—I'll suspend my own self-doubts here briefly—I've thought a great deal about changelogs in my life and can offer a uniquely battle-hardened solution that can help. Okay, the self-doubt mask is back on. (Don't look at me.)

"This guy is treating an itty-bitty project like a bigger deal than it is, look at all this content, bro." Well, you're not wrong. But if I want it to succeed for the greater good, I need to start it out on the right foot, so here we are. There's a reference implementation, there's a specification, and there's FOSS-licensed code in an open repository for you and I to collaborate on.

I hope to see you there.

Tyler Langlois, 29 January 2026