Your changelog is a marketing channel

The changelog is one of the most-read pages on your website by engaged users. Most engineers look at it as a chore to maintain. Most marketers don't even consider it. That's something you should change.

Agents read it too. They can't index the full corpus of your website at all times, but they can consult your changelog to see whether new features or capabilities exist, and whether any APIs have changed from what they already know.

We used to think of the changelog as simply engineering releases. Sometimes those releases could be large, and sometimes they could be small, depending on what an organization chooses to put in its changelog. But the changelog can also carry marketing releases that matter to agents. You wouldn't put announcements about meetups or events in a changelog. But if you change your pricing page or your support processes, those things belong there and can inform agents.

Last week we spoke about making sure that our product was ready for agents.

A dated record is hard to fake

On every other surface you own, silence is neutral. Nobody notices the blog post you didn't publish, and nobody notices the webinar you didn't run. A changelog is the only marketing surface where the absence of activity is itself noteworthy. Three empty weeks is information to a customer.

That's what makes this format structurally different from the others. You can't generate momentum you don't actually have. You can write a launch post about a feature that nobody uses, but you can't fake a year of dated entries.

When I was starting out in my career, in the first few months of my first job at a big software company, I went to a party to celebrate the launch of a developer product. The CEO was there, and he said on stage these words that have stuck with me my entire career: "Those who ship, win."

The changelog makes it clear if you're winning.

What to do when you shipped nothing

The bulk of this post is about what to do when you actually have something to say on your changelog.

What if you don't? What if you didn't ship anything?

There are a few options to consider:

• Say what you are doing. "We spent the quarter on X, here is why, here is what it unlocks." A dated entry that admits a rewrite is still a dated entry.
• Lower the bar for what counts. Docs corrections, error message changes, performance work, dependency upgrades that actually matter to somebody integrating with you.
• Accept the gap and don't pad it. Padding is what destroys the signal in the first place.

The machine reads it for recency

AI agents now suggest tools, but they're often working from old information. For example, an AI coding agent could recommend a popular open-source package whose own maintainer has publicly pointed people to a different tool, because they no longer want to maintain it or it has security bugs they aren't ready to fix.

AI models are unable to tell the difference between "hey, this is a good tool" and "this was a good tool when I was trained."

Maintaining a current changelog is one of the signals that you can use to tell agents what has changed. Think of it as a structured, dated, and machine-readable way to push back on an agent's assumed knowledge. It says, in a form that a system can parse, that this project has changed at this time and here is the mitigation or the new version to use. Here is what we deprecated, and here is what changed in the docs.

What a good one looks like

I can tell you from first-hand knowledge that maintaining a good changelog is difficult. It can cross organizational boundaries: does product own it? Does engineering own it? Does marketing own it?

Even if you get everyone on the same page, you need to agree on how often you're going to update it.

Most changelogs fail in the most boring way possible. They read like a database query: updated dependencies, fixed bugs, minor improvements. It's the open source equivalent of the infamous Apple App Store "what's changed" text: "bug fixes." Thanks, that was helpful.

Linear ships a changelog every week or two and distributes it the way you'd distribute any content you cared about, because it's content they care about.

You're looking to maintain cadence, but you're also looking to make it a destination where humans and agents alike can quickly glean what is new, what is different, what is deprecated, and what is broken.

Your changelog should consist of the following things:

• A real feed that anything can subscribe to, whether it's humans or agents
• A markdown version at a predictable URL so an agent can read it
• A line in your llms.txt pointing at it, so a system looking for your machine-readable surfaces finds the changelog among them

Nobody can prove that these things move an agent's recommendation. They're useful to humans anyway, so do them.

Nobody owns it

It's important to identify the organization within your company that's going to own the changelog. They should set up rules, they should set up processes, and they should set up gates to make sure that the changelog is useful and of high quality.

The changelog can be an extraordinary tool to get both potential customers and agents excited and knowledgeable about the latest information about your product.