Browser extension release notes: shipping updates users never asked for

Browser extensions live in the strangest corner of software distribution. Like a web app, your updates reach users without them doing anything — the browser fetches new versions quietly in the background. Like a mobile app, a store review process sits between you and shipping, on a clock you don’t control. And unlike either, a routine version bump can disable your own extension in every browser it’s installed in, if it asks for one permission too many. This guide covers release notes for that world: where they can actually live (the stores give you less than you’d think), how to write the permission-change entry that decides whether people keep you installed, and the update etiquette that separates beloved extensions from uninstalled ones.

Updates nobody asked for, on a schedule nobody controls

Two clocks run every extension release, and you set neither:

  • Store review. You submit; the store reviews. Chrome Web Store review usually clears in a day or two but can take much longer, especially when the update touches permissions or remote code. Firefox’s AMO has its own review pipeline. You find out the version is live roughly when your users do.
  • Rollout. Once published, browsers pick up the update on their own polling schedule — hours for some users, days for others (and longer for browsers that were closed all week). At any moment, several versions of your extension are alive in the field at once.

Three practical consequences for the changelog:

  • Write the notes before you submit, date them when the store publishes. The entry should exist the moment anyone can have the new version, and its date should match what users can see in the store — not the day you tagged the release.
  • Every bug report needs a version number. With overlapping rollouts, “after the update” means nothing. A dated, versioned changelog is how you — and your users — work out which release a symptom belongs to.
  • You can’t hotfix fast, so communicate instead. A bad extension release can take days to fully replace. The two-pass hotfix pattern — acknowledge at once on a page you control, update the same entry when the fixed version clears review — matters more here than almost anywhere.

Where release notes can actually live

The honest answer: the stores barely give you a changelog surface, which is why so many extensions effectively don’t have one.

  • Chrome Web Store: no changelog field at all. There is a description, and that’s it. Some developers paste a “What’s new” block at the top of the description — it’s unversioned, it overwrites itself every release, and almost nobody revisits a store listing after installing. It is a teaser at best, never an archive.
  • Firefox AMO: real per-version notes. Each submitted version has a release-notes field, shown on the add-on’s version history page. It’s the best store surface any browser offers — and it’s still buried two clicks deep, read mostly by reviewers and power users. Fill it in (reviewers genuinely read it), but don’t mistake it for reaching your users.
  • Inside the extension. A small “What’s new” link or panel in your popup or options page — the only surface guaranteed to be one click from an actual user. Pair it with a subtle badge on the toolbar icon for noteworthy releases, following the same indicator-panel-seen rules as an in-app widget: never a modal, never auto-opened.
  • A hosted changelog page you control. The only surface that is versioned, dated, permalinked, identical across Chrome/Firefox/Edge, and readable by someone deciding whether to install at all.

The setup that works is the two-layer pattern from mobile: a canonical hosted changelog plus thin store-shaped slices — AMO’s version notes get the entry, the CWS description block gets one line and a link, the in-extension panel links to the full page.

Permission changes: your highest-stakes entry

When an update requests new permissions, Chrome doesn’t install it quietly. It disables the extension and shows the user a warning that it wants new powers — phrased in the store’s scariest generic language (“Read and change all your data on all websites”), with no room for your explanation. Faced with that prompt cold, a large share of users choose Remove. For an extension, a careless permission bump is a breaking change you inflict on yourself.

The playbook:

  • Avoid the prompt entirely when you can. Use optional permissions requested at the moment the user invokes the feature that needs them. A permission asked for in context, for a visible reason, converts; the same permission demanded at update time terrifies.
  • Announce before you ship. A dated entry — posted a release ahead — saying exactly which permission is coming and why: “v3.0 will request access to github.com so the PR checklist can run there. It runs nowhere else.” Link it from the in-extension panel and the store description before the prompting version lands.
  • Name the permission precisely, explain the mechanism plainly. Which hosts, which API, triggered by what. The generic store warning is vague; your entry is where the vagueness gets repaired. “We request tabs to restore your session after a crash” beats a paragraph of reassurance.
  • Put the entry’s permalink everywhere the scared user might look: store description, support threads, the review replies you’re about to write.

And the habit that costs nothing: end routine entries with “Permissions: unchanged.” It’s one line, it’s verifiable, and for the reader deciding whether your extension is still the thing they installed, it’s the most reassuring sentence you can write.

Update-page etiquette (onInstalled is loaded)

Extensions can detect their own update and open a page about it. This is the most resented pattern in the ecosystem — the user was mid-task in their browser, and your tab-out-of-nowhere is exactly the interruption they installed an extension to avoid. Rules:

  • Routine updates open nothing. Fix releases, minor tweaks: badge at most, usually silence. The changelog absorbs the details for whoever cares.
  • Major, user-visible releases may earn one page, once. If the UI changed or the user must act, a single what’s-new tab on a genuinely major version is defensible. Gate it on the version delta, not on the update event itself — the update hook fires for every patch.
  • Never open a tab for the release that adds tracking, monetization, or permissions-adjacent changes and bury the fact mid-page. Users screenshot these. The tab that was supposed to celebrate becomes the evidence.
  • The gentler default: toolbar-icon badge → panel → “See the full changelog” link. Attention borrowed, never seized.

Trust is the whole game

Extensions run inside the browser with access mobile apps can only dream of, and the ecosystem’s history — extensions quietly sold to data brokers, update-delivered malware, adware injections — means informed users treat every extension as suspect by default. Store policies exist for this (Chrome requires disclosed, justified permissions and honest data-use declarations), but policy compliance is the floor. The changelog is where you clear it visibly:

  • Any change to data collection, ownership, or monetization is a loud, dated entry. New analytics, a new owner, an affiliate integration — announced in plain words, before or with the release. Discovered silently, any of these reads as a betrayal and earns the review-bomb it gets.
  • Security fixes follow the same rules as everywhere else: precise about impact, vague about recipe until the fixed version has rolled out — and never silent.
  • An unbroken dated history is itself the signal. The cautious user deciding whether to install checks two things: when was this last updated, and does the developer explain what updates do. A public changelog answers both in one page.

An entry template

## 2.6.0 — live on Chrome Web Store & Firefox AMO

**New:** Highlight colors — pick per-site colors in Options.
**Fixed:** Sidebar no longer overlaps reader mode on Firefox.
   (Thanks to everyone who reported this one.)

Permissions: unchanged.
Rollout: submitted to both stores today; browsers typically
update within a few days. Check your version at the bottom
of the Options page.

Version, store-publication date, changes in reader terms (symptoms, not internals — most extension users are not developers), the permissions line, and a rollout note that explains why “I don’t see it yet” is normal.

Anti-patterns

  • The description-only changelog. A “What’s new” block in the store description is unversioned, unlinkable, and overwritten every release. History that overwrites itself isn’t history.
  • A tab on every update. The fastest way to teach users that your updates are interruptions — and to farm one-star reviews from people you interrupted.
  • “Bug fixes and improvements,” forever. With silent auto-updates, vague notes mean your users have no idea what code they’re now running. For software this privileged, vagueness curdles into suspicion.
  • A permission prompt with no matching entry. The scariest dialog your user will see this week, and searching your name + “new permissions” finds nothing? Remove, report, one star.
  • Silently removing features. Auto-update means the user discovers the removal mid-task, with no warning and no explanation. The reviews section becomes your changelog, written by your angriest users.
  • Version soup across stores. Chrome at 2.6, Firefox stuck at 2.5 in review, and nothing anywhere saying which store lags. One canonical changelog noting per-store status (“2.6 live on CWS; AMO in review”) dissolves the confusion.

One canonical changelog, sliced per store

Wakelog is built to be the canonical layer: post the entry from your release script with one curl (or wakelog post --from-git) when you submit, keep it as a draft until the store approves, publish the moment the version is live — then paste the same text into AMO’s version notes and drop one line + link into the CWS description. You get stable permalinks for permission explanations and review replies, tags (new / fix / security / announcement), RSS for your power users, and a “What’s new” URL your options page can link to forever. If you’ve been shipping without notes, start from today — entry zero, no backfill guilt.

Start your free changelog   Next: app store release notes →

Related guides

Last updated 2026-07-27 · All guides