Video release notes: turn your changelog into short clips

A changelog tells people who are already looking. A short clip reaches the people who aren't. It doesn't replace written notes, which remain the record. It's the part of a release that travels.

Which releases deserve a clip

Most releases don't. A clip of a dependency bump teaches your audience to ignore you. Keep a Changelog sorts changes into six types, and those make a good filter.

Decide on a rhythm too. If you ship weekly, one clip a fortnight or a monthly roundup is plenty. A steady, modest cadence beats a burst of ten clips followed by silence.

Rewrite the notes for people

Keep a Changelog opens with a principle worth keeping: "Changelogs are for humans, not machines." Auto-generated notes usually aren't. On GitHub, automatically generated release notes give you a list of merged pull requests, contributors and a link to the full changelog. That's a fine record, but a poor script.

Here's a made-up release from Acme Invoices, an invented product:

One row survives, which is the right result. A clip is about one thing.

You can make this filtering easier at the source. GitHub lets you add .github/release.yml to exclude labels or bots, such as dependency updates, and group pull requests into named sections. Label your user-facing work and the feature list almost writes itself. It's also worth writing a one-line summary at the top of each release, in plain words, because that's what a feed-reading tool will pick up first.

A script for a 15-second clip

Three beats are enough: what's new, how it works, where to find it. For the example above:

Note what isn't there: no version number, no "we're excited to announce", no thanks to the team. Start with the benefit, because the first seconds of a clip decide whether anyone stays. For fuller examples at other lengths, see product demo scripts with word counts.

Use a real screen from the shipped feature. It proves the feature exists, and it's easier to make than an abstract graphic. If a release has no visual change, such as a speed or API improvement, use a simple typographic clip or don't make one.

Choose the format for each channel

If you use a GIF, keep it small. Programmable's GIF export runs at 8 fps for up to 12 seconds, so keep to one action. On a web page, prefer a video: web.dev's guide, last updated in 2018, shows a 3.7 MB GIF becoming a 551 KB MP4 or a 341 KB WebM.

Automate the first draft

You can set up the routine so that each release arrives as a draft instead of a chore. Any source with a feed works. GitHub publishes one for each repository's releases at https://github.com/owner/repo/releases.atom.

In Programmable, watching a feed is included with paid plans, from Starter up. The feeds help article has the full steps:

1. Go to Publish › Feeds and choose Watch a feed.
2. Pick RSS or Atom for a blog or changelog, or GitHub releases / changelog and paste the repository address.
3. Choose a format. The options include a landscape story of 30 seconds, a portrait social clip of 18 seconds, and a 12-second vertical launch clip that takes a bold line and the top changes from each release.
4. New posts appear from then on under New posts, marked Ready to animate. Earlier posts aren't picked up.
5. Open one, review the brief, and make it in one click.

If your workspace uses Programmable's AI, posts can also be queued to generate in the background. If you use your own AI keys, nothing runs while you're away, and posts wait for you. For a batch of clips from other kinds of posts, see the social clips use case.

The studio reads your feed with no sign-in, so the repository needs to be public. For a private repository, publish a public changelog with an RSS feed and watch that instead.

Keep a person in the loop

Automation makes the draft. A person should still approve what goes out.

• Check the notes first. A feed takes whatever the release says. If your notes are a list of pull requests, the brief will be too, so tell the studio which item matters. Writing a good summary pays off here.
• Watch for builds that aren't releases. A release feed can include nightly builds. Neovim's feed, for example, lists a nightly development build alongside its versions, with notes that are mostly install instructions. A clip of that helps nobody, so leave auto-generate off for a noisy feed.
• Check what the animation claims. The studio works from your text and doesn't know what you've really shipped. Confirm it against the product.
• Show the real feature. A feed only supplies the words. For a true demo, start a product demo from a screenshot of the feature and paste in the release note.
• Hold back anything unannounced. If you ship behind a flag, a public release note can reveal it early. Keep private details out of notes that will become clips, and read how to keep customer data out of screenshots before capturing the real feature.

In a team workspace, approvals can require sign-off before links and embeds show a new version.

What usually goes wrong

• Too much in one clip. A clip listing five features lands none of them. Choose one, and link to the rest.
• Internal language. Your customers don't know what a "workspace-scoped entitlement" is. Use their words.
• Publishing before it's live. Roll out first, or say clearly who has it. A clip for a feature people can't find produces support tickets.
• No next step. End with where to find it, and put a link in the post.
• Starting big and stopping. Choose a rhythm you can keep for a year.

When a clip is the wrong answer

Some changes need more than 15 seconds and shouldn't be condensed. A breaking API change or a pricing change belongs in a written notice sent directly to the affected people. A migration needs documentation. A walkthrough of several minutes needs a screen recording, because Programmable stops at 60 seconds and doesn't output real footage. And if you have only a few customers, a personal message from you will usually do more than any clip.

Common questions