The entry gets scanned before it gets read
A changelog is a list, and lists get skimmed. Whatever your release notes look like, the reader is running down headlines waiting for one that sounds like their problem. The loop under that headline is doing two jobs at once: it has to be recognizable at a glance while they are still moving, and legible once they stop.
That makes frame one a decision rather than a byproduct of where you happened to drop the in point. Start on the state that shows the feature working, not on an empty screen and not on a cursor halfway to a menu. A reader who never watches the animation should still be able to name the change from the still image.
One entry, one behavior, three to six seconds
Release-note GIFs usually go wrong by trying to show the release rather than the change. A loop that pans across three new menu items teaches none of them, and the reader who cared about exactly one has to watch the other two.
- A new control: show it being used and what happens next. Nothing before it, nothing after.
- A speed improvement: the loop is the thing finishing. That is one of the most convincing GIFs a team can ship and almost nobody makes it.
- A new setting: show the setting's effect on the product, not the settings page with a new row in it.
- An invisible change, an API, a migration, a security fix: write the sentence and skip the image. A decorative loop on a backend entry teaches readers to scroll past every loop you publish.
Scope discipline is also file-size discipline. The three seconds that show one thing weigh a quarter of the twelve seconds that show four, and read better.
Ten megabytes is a wall, not a budget
If your changelog lives on GitHub, the documented ceilings for attachments on issues, pull requests and release notes are 10 MB for images and 25 MB for other files. Hosted changelog tools and static-site builds have their own numbers. None of them are targets. The real constraint is that a changelog page renders many entries at once.
Ten entries at 3 MB each is a thirty megabyte page, and the person loading it is usually on a phone, having tapped a link from a release email. Keep each loop under roughly 1 MB, lazy-load everything past the first screen, and consider MP4 for the newest entry at the top, since H.264 encodes the motion between frames while GIF pays for the frames themselves. The Output Format switch takes the same trim out either way, so it costs nothing to try both and compare, and the measured file sizes show how far apart they land.
Your loop ages faster than the sentence next to it
A changelog is an archive. The entry from fourteen months ago stays published forever, and so does its GIF. By then the button has moved, the brand color has shifted, and the sidebar has grown two items. The prose survives because it describes what changed. The image does not, because it describes what the product looked like on a Tuesday in spring.
Two habits keep an archive from turning into a museum of old interfaces. Crop tight, so the loop shows the component rather than the surrounding chrome that gets redesigned first. And save the project file, so refreshing a stale entry means re-recording and re-exporting against the same trim, crop, and captions instead of reconstructing the whole thing from memory.
The third option is to decide on purpose that old entries go stale, and say so at the top of the page. That is a perfectly respectable answer. Quietly serving a loop of an interface that no longer exists, while support fields tickets about a button nobody can find, is not.
Shoot it from the branch while the change is still warm
The reason most changelog GIFs are late is that they get made after the release, from production, by somebody who was not in the pull request. Capturing from a local build or a staging tab while the work is fresh is faster, more accurate, and puts the loop in the PR description where reviewers actually see the behavior they are approving. The README guide covers the hosting side of that.
That footage is pre-release by definition, often with seed data or a real account on screen. Record a Tab in the editor captures the staging tab from inside the page itself, and the encode runs on your processor, so an unshipped build never travels to a converter to be turned into a marketing asset. If something confidential is in frame anyway, a shape overlay covers it before the export rather than after.