One changelog for designers and developers

What you’ll learn

Every release leaves a trail in three different places: the commits developers push, the versions designers publish in Figma, and the design tokens that change underneath both. Most teams stitch those together by hand, badly, the night before a release. This tutorial teaches ds-bridge’s changelog command, which reads all three sources and prints one changelog split into a For designers section and a For developers section — so each audience reads the half that matters to them without missing the changes that matter to everyone.

A reassuring word for designers and managers reading along: you don’t need to understand git to use this. The command does the reading; you get a tidy, plain-language summary. And it’s safe by design — changelog only ever prints to your terminal. It writes nothing to your repo, Figma, Confluence, or Slack on its own.

• How changelog aggregates git commits, Figma versions, and token changes
• How conventional-commit prefixes (feat, fix, feat!) become severities
• How to segment the output by audience and export paste-ready markdown
• Why the Figma side is skipped when no token is set — and why that’s fine

Setup

You’ll need the ds-bridge plugin and a project that is a git repository — that’s the one hard requirement, because local git history is the always-present source. New to ds-bridge? Getting started covers install and the preferences dialog first; come back here when you’re set up.

Everything below was captured by running the command against the ds-bridge repository itself, so the output is real git history — your own runs will look the same shape against your own commits.

# A changelog of everything since a date, as markdown.
ds-bridge changelog --since 2026-06-05 --format=md

Steps

1. Run a full changelog and read the split. With --format=md, ds-bridge prints a markdown document already divided into the two audience sections. Here’s a real run against the ds-bridge repo (trimmed — the full window had 86 entries):

   # Changelog
   
   ## For developers
   
   ### 2026-06-06
   
   - **[notable]** a11y + impact dashboard sections, history lines, six-artifact acceptance (T7.22) — lucksy
   - **[minor]** build dist once via vitest globalSetup - kill concurrent-rebuild race (T7.23) — lucksy
   - **[notable]** ds-docs command (T7.20) — lucksy
   - **[notable]** docs generation command (T7.19) — lucksy
   - **[notable]** a11y-check command (T7.4) — lucksy
   
   ### 2026-06-05
   
   - **[notable]** a11y contrast command (T7.3) — lucksy
   - **[notable]** impact command (T7.10) — lucksy
   …
   

   Notice the shape: a ## For designers and a ## For developers heading, each with entries grouped by date (newest first), and every line led by a severity badge — [breaking], [notable], or [minor].

2. Read how commits become severities. This is the heart of the code side. ds-bridge classifies each git commit by its conventional-commit prefix:

   • feat: → a notable change, filed under developers. New features are worth announcing.
   • fix: → a minor change, filed under developers. Bug fixes are real but quieter.
   • feat!: or a BREAKING CHANGE: footer → a breaking change, and breaking changes are surfaced first in their section so they’re impossible to miss.
   • Anything that isn’t a recognised conventional header (a checkpoint tag, a plain subject) falls back to minor.

   You can see this in the run above: the one fix(tests): build dist once… commit landed as [minor], while every feat(…) commit landed as [notable]. This repo’s window happened to contain no breaking commits, so you won’t spot a [breaking] badge here — the first feat! or BREAKING CHANGE: you ship is the first one you’ll see.

3. Narrow to one audience. Pass --audience designers (or developers, or the default both) to render only that section. Here’s the honest result of asking this repo for the designers’ view:

   # Changelog
   
   _No changes in the selected window._
   

   That isn’t a bug — it’s the truth. The ds-bridge repo has lots of developer commits but no labeled Figma versions and no token changes in this window, so the designers’ half is genuinely empty. On a real product repo, where designers publish named Figma versions, this is exactly where their milestones would appear.

4. Watch the Figma side skip itself, honestly. Run the same command with the human-readable --format=term and look at what ds-bridge prints to stderr:

   Figma side skipped (no token / file key configured) — code + token changes only.
   

   This one-line note is a feature, not an error. With no Figma personal access token and file key configured, ds-bridge can’t read Figma version history — so instead of failing, it tells you plainly that it’s reporting code and token changes only, and carries on. That’s what makes changelog work completely offline, straight from a plain git repo. Add a token (see Getting started) and labeled Figma versions start flowing into the For designers section automatically.

Result

You can now produce one changelog that two audiences will actually read. The developers section carries the commit story, severity-tagged; the designers section carries published Figma milestones and the token changes that cross both worlds. A breaking change is never buried — it leads its section.

A few things worth knowing for everyday use:

• Three formats, one job. --format=term is the friendly terminal view, --format=md is paste-ready for a release note or wiki page, and --format=json is the structured shape the slash command consumes.

• It’s a generator, not a gate. Exit code 0 means it ran — whether or not there were any changes. You only get exit code 2 for an operational problem: a bad --format or --audience value, or running outside a git repository. That makes it safe to drop into a release pipeline without worrying it’ll fail your build for having changes:

  # In CI: generate release notes; never blocks the pipeline on "has changes".
  ds-bridge changelog --since "$LAST_TAG_DATE" --format=md > RELEASE_NOTES.md
  

• Posting is model-led and ask-first. Want this in Confluence or Slack? The CLI will never post anywhere itself — it has no integration and prints to stdout only. Run /ds-bridge:ds-changelog instead: it generates the markdown, shows it to you, and will publish only through a tool you’ve already configured and only after you explicitly confirm the exact destination. No guessing, no surprise posts.

Troubleshooting

• Everything lands under “For developers”? That’s expected when there are no labeled Figma versions and no token changes — look for the Figma side skipped note on stderr. Configure a Figma token and publish named versions in Figma to populate the designers’ side.
• The designers’ section is empty? Same cause. ds-bridge filters out Figma autosaves on purpose and only shows versions you’ve given a label — so a designer needs to publish at least one named version inside your --since window.
• --audience designers printed an error? Mind the spelling: the accepted values are designers, developers, and both. Anything else exits with code 2 and a one-line message telling you the valid options.
• --since matched nothing? It takes any date git understands (an ISO date like 2026-06-05 is simplest). With no --since at all, ds-bridge looks back 90 days by default — widen the window if your last release was further back.