Integration release notes: shipping updates inside someone else’s product

An integration lives inside a product you don’t own. Your code runs in someone’s Slack workspace, Shopify store, Jira project, or Zap — installed once, by one person, then used every day by people who may not even know it’s a third-party app. You deploy continuously, so updates arrive with no install step, no version prompt, and usually no version number at all. The marketplace that distributes you gives you almost no changelog surface. And the single scariest thing you can ship isn’t a bug — it’s a re-authorization prompt landing on an admin who forgot you exist. This guide covers release notes for that world: who actually reads them, where they can live, how to write the permission entry that decides whether you stay installed, and the etiquette of announcing things inside a product that isn’t yours.

Three readers, one install

Most software has one reader per install. Integrations have three, and they want different things:

  • The installing admin. They connected you, approved your OAuth scopes, and answered for you in a security review. Every re-authorization prompt, breaking change, and data-access question routes to them — often months after they’ve forgotten the details. They need dated, linkable history: what changed, when, and what you can touch now that you couldn’t before.
  • The everyday user. They use “the thing in Slack” or “the app in the store admin.” Many don’t know it’s a separate vendor. When your update changes behavior, it reads as the platform changing — they won’t search your website; they’ll ask their admin or the platform’s support. Entries for them must be written in symptoms and screens, not internals.
  • The platform’s reviewer. Marketplace review teams and the procurement people who vet vendors both ask the same question at different moments: does this vendor communicate changes? A public, dated changelog is the answer you can link instead of writing a fresh essay every time.

One changelog can serve all three — but only if entries lead with the user-visible change and carry the admin-relevant facts (scopes, data access, action required) as structured, skimmable lines.

Versionless by default: date-based entries

Most integrations are hosted services: you deploy, everyone’s on the new behavior, nobody chose to upgrade. There’s no version for a user to check and no “what version are you on?” triage question — which makes the changelog the only record of when behavior changed. Run a dated stream, not version headings: the entry’s date is its identity, and “why did this start happening on Tuesday?” becomes answerable.

Two real exceptions. Atlassian apps for Data Center install specific versions into customer-run instances — those need true per-version notes like any on-prem release. And Zapier integrations are explicitly versioned: you publish a new version and existing Zaps are migrated to it. A migration that changes trigger payloads or field names can silently break workflows people built months ago — treat a version promotion like a release, with an entry, even though no user pressed an update button.

What the marketplaces actually give you

Less than you’d hope. Survey of the big ones:

  • Atlassian Marketplace is the rare luxury: listings have a real version-history tab with per-version release notes. Use it — buyers genuinely read it — but treat it as a mirror of your canonical page, pasted at release time.
  • Slack App Directory has no changelog surface. Your listing describes what the app does today; history goes elsewhere.
  • Shopify App Store likewise: no version-notes surface merchants can browse. What merchants do see is a permission-approval banner when your requested access changes — which is precisely when they’ll go looking for an explanation you’d better have published.
  • Zapier shows users nothing about integration versions; the versioning machinery is developer-facing. If a migration changes visible behavior, the only place users can learn that is your changelog.

The conclusion is the same two-layer pattern as app stores and browser extensions, with the weights shifted further toward you: the canonical changelog lives on your domain (permalinks, feeds, search-indexable), and each marketplace gets whatever slice its format allows — a version-notes paste on Atlassian, a “What’s new” link in your Slack and Shopify listings’ descriptions and support URLs.

The re-authorization entry (get this one right)

Scope changes are the highest-stakes release an integration ships. On Slack, new scopes mean an admin must re-approve; on Shopify, merchants see an approval screen for the new access — and until someone acts, some or all of your integration may simply stop working. The prompt lands cold, on the installing admin, phrased in the platform’s scariest legalese (“This app wants to view messages in all channels”), with your name on it.

The playbook — close kin to a breaking-change announcement:

  • Announce before you request. Publish the entry (and, for action-required changes, notify installing admins directly) at least a release ahead of the prompt. A pre-announced prompt is a checkbox; a surprise prompt is a security incident in the admin’s head.
  • Name the exact scope and the feature that needs it. “We now request files:read so the attachment preview you turn on in Settings can render — we never fetch files unless preview is enabled.” Precise scope, plain reason, honest boundary.
  • Say what happens if nobody acts. “Existing features keep working; previews stay off until an admin approves” reads very differently from “the integration pauses until re-approved.” Whichever is true, print it, with dates if there’s a deadline.
  • Keep the entry’s URL stable and put it everywhere the prompt might send a confused admin: the notification email, the listing’s support link, your app’s settings page. That permalink is the entry’s whole job.
  • Print “Scopes: unchanged.” on routine entries. One line, nearly free, and it builds the habit that makes the rare scope entry impossible to miss — the same trick as the permissions line in extension release notes.

When the platform forces your hand

Platforms deprecate APIs on their schedule, not yours. When the platform retires an endpoint you depend on, you rebuild on the replacement and — if you’re unlucky — something visible shifts: a trigger fires differently, a field disappears, a workflow needs re-connecting. Your users never asked for any of it, and they will blame the name they can see: yours.

The entry that keeps their trust does three things: names the cause without hiding behind it, owns the outcome, and is concrete about action. “Slack is retiring the API our channel sync used. We’ve moved to the replacement — sync now updates within a minute instead of instantly. Nothing to reconfigure.” Cause, consequence, action (none). If the platform’s deadline forces users to act by a date, that’s a deprecation-style entry with the platform’s date printed, a reminder scheduled, and a direct notification to installing admins — “the platform made us” explains the why, but the dates and the migration path are your job.

Announcing inside someone else’s product

Integrations have push channels most products only dream of: the bot can DM every user, post to channels, fill a home tab, banner the store admin. This is exactly why restraint is the differentiator — you are a guest in someone’s workspace, and the host decides what’s spam:

  • Routine changes: changelog only. Fixes, small improvements, internal work — they go on the page, into the quiet “What’s new” surface in your app’s own dashboard or home tab, and nowhere louder.
  • Action-required changes: notify the installing admin, once. Re-auth, breaking behavior, sunsets — a single direct message or email to the person who can act, linking the permalink. Not a broadcast to every user who can’t.
  • Feature launches: almost never a DM. A bot that DMs a thousand workspaces about a feature launch gets uninstalled by admins who were burned before. If the feature is visible where people already work, it announces itself; the changelog and your community channels carry the rest.

You hold the keys: the trust ledger

An installed integration is a standing OAuth grant to someone’s customer data. Vendors with that kind of access get security-reviewed at install time and re-reviewed at renewal — and “how do you communicate changes?” is a standard questionnaire row. An unbroken, dated public changelog — scope changes flagged, security fixes handled with advisory discipline, platform migrations documented — is evidence you can link in every review (compliance reviewers read changelogs the way engineers read diffs). Silence cuts the other way: a privileged app with no public history of what it changed reads as a risk, because it is one.

An entry template

## 2026-07-29 — Attachment previews in channel digests

**New:** Digests can now include image previews for shared files.
Turn it on per-digest under Settings → Digests.

Scopes: one addition — files:read, requested only when you
enable previews. Slack will ask a workspace admin to approve.
Nothing else changes if you leave previews off.
Platform status: live for all workspaces; no reconnection needed.

Dated (versionless service), the change in user terms, the scope line with its honest boundary, and a platform-status line that answers “do I have to do anything?” before anyone asks.

Anti-patterns

  • Integration news buried in your main product’s changelog. Your Slack app’s users are not your web app’s users. If the integration’s changes live as occasional lines in another product’s stream, its actual audience — admins hunting for “what changed in the thing I installed” — finds nothing. A stream (or tag) per integration surface.
  • A scope prompt with no explanation anywhere. The admin searches your name plus “new permissions” and gets nothing. Denied, uninstalled, flagged in the next vendor review.
  • The all-workspace launch DM. One broadcast about your new feature converts a few users and teaches every admin you’ll do it again.
  • “Improvements to our Slack app,” forever. Vague notes from software that reads private channels is not modesty; it’s suspicious. Privileged access raises the specificity bar.
  • Blaming the platform, skipping the dates. “Due to upcoming Shopify changes, some features may be affected” — no what, no when, no action. The platform set the deadline; you still owe the migration entry.
  • The silent version migration. Promoting a Zapier version that renames output fields, with no entry, breaks Zaps built on the old names — and the people debugging them have no idea anything shipped. No user-visible install step doesn’t mean no release happened.

One canonical page, sliced per marketplace

Wakelog is built to be the canonical layer under all of this: a project per integration (or tags per surface), stable permalinks you can put behind every scope prompt, listing support link, and admin email, and a dated stream that fits versionless services naturally. Write the entry when you submit for marketplace review as a draft, then schedule it with publish_at for approval day — same two-clock trick as app stores. Feeds (RSS + JSON) give the ops teams that monitor their vendors a machine-readable surface, and webhook mirrors post each release to your own community Slack or Discord. Honest caveat: Wakelog won’t message anyone inside the platform for you — deciding when a change deserves an admin’s attention is exactly the judgment call you shouldn’t automate. If your integration has been shipping silently, start from today — entry zero, no backfill guilt.

Start your free changelog   Next: browser extension release notes →

Related guides

Last updated 2026-07-29 · All guides