# Writing Release Notes

> Write user-facing release notes for a Bitwarden release from a Jira release tag and the

- Skill: `bitwarden/writing-release-notes` (Agent Skill)
- Install (CLI): `npx skillmds@latest add bitwarden/writing-release-notes`
- Raw SKILL.md: https://api.skillmd.com/api/skills/bitwarden/writing-release-notes/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: bitwarden (https://skillmd.com/u/bitwarden)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/bitwarden/writing-release-notes

---


# Writing Release Notes

Produce concise, user-facing release notes for a Bitwarden release. The output is what customers read — on GitHub, in the App Store, or in Google Play — so every word should be benefit-oriented, jargon-free, and accurate about what users will actually experience.

## Prerequisites

Automated Jira lookups require the `bitwarden-atlassian-tools` plugin (its MCP server exposes `search_issues`, `get_issue`, and `get_issue_comments`). Without it, or when running in a Claude.ai Project (MCP tools are unavailable there), fall back to asking the user to paste the release page content and the Slack thread text directly — the rest of this skill works identically either way. There is no Slack MCP integration in this marketplace; the Slack thread is always gathered by asking the user to paste it.

## Step 1: Gather Inputs

Gather two inputs before writing anything:

### 1a. Jira Release Page

Ask the user for the Jira release page URL (e.g. `https://bitwarden.atlassian.net/projects/CL/versions/12345/tab/release-report-all-issues`) or the release version name (e.g. `2025.7.0`).

If `search_issues` is available, resolve the query:

- From a URL, extract the numeric version ID (the segment after `/versions/`) and query by ID: `fixVersion = 12345 ORDER BY issuetype ASC`
- From a version name, quote it: `fixVersion = "2025.7.0" ORDER BY issuetype ASC`

Call `search_issues` with `fields: ["summary", "issuetype", "labels", "components", "status", "description"]`, and page through results using the returned `nextPageToken` until none is returned. For each issue, capture summary, issue type, labels, components, status, and any feature flag references found in the description. Feature flag references usually surface more completely in the Slack thread (Step 1b); only call `get_issue_comments` for individual issues where the flag is ambiguous after checking both sources.

If MCP tools are not available (web app context), ask the user to paste the release page content or a list of ticket summaries directly into the conversation.

### 1b. #release Slack Thread

The #release Slack thread is posted weekly and specifies which feature flags are toggled for the release. This is critical for two reasons:

- **Include**: Only user-facing changes whose feature flag is being enabled in this release (or that have no flag) should appear in the notes.
- **Flags enabled with no matching issue in this release**: don't assume there's nothing to report — see the Step 3 investigation.
- **Server releases — flag removals**: When a feature flag is being fully removed from the server codebase, this signals that self-hosted users are gaining access to the feature. These must appear in the release notes.

Ask the user to paste the thread content.

Parse the thread to extract:

- Release version and date
- List of flags being **enabled** for this release (per platform if specified)
- List of flags being **removed** (for server releases — capture both the flag identifier and any associated feature description from the ticket or thread)
- Any PM or engineering notes about what to highlight or suppress

## Step 2: Determine Release Scope

Identify:

- **Which repo/product** is being released (clients, server, mobile, browser extension, CLI, desktop)
- **Which platforms** are covered (web app, desktop, browser extension, mobile iOS, mobile Android, CLI)
- **Release version** number

If the release covers multiple repos with separate release notes (e.g., clients and server each have their own GitHub release), confirm with the user whether they want notes for all or one.

## Step 3: Filter to User-Facing Changes

Go through every issue in the release and classify it. Only items that pass the filter appear as named bullet points.

### Include as a named bullet point

- New user-visible features or capabilities
- UI or UX changes users will notice
- Policy and admin setting changes (including new enforcement options)
- Performance improvements users will perceive
- Significant accessibility improvements
- New onboarding flows, product tours, or setup wizards
- Checkout, billing, or subscription flow changes
- Items whose feature flag is confirmed **enabled** in this release's Slack thread
- Flags confirmed **enabled** in the Slack thread with no matching issue in this release's Jira list, but only once the investigation below shows the guarded feature is itself user-facing

### Collapse into the catch-all line

- Internal refactors, code cleanup, or architecture changes with no user-visible effect
- Dependency upgrades with no user-visible change
- Test coverage additions
- Logging, telemetry, or analytics instrumentation
- Items behind a feature flag that is **not** being enabled in this release
- Flags confirmed **enabled** in this release whose guarded work turns out to be an internal refactor, infrastructure change, or other item that would collapse under these same rules if it had shipped with a ticket in this release
- Minor copy or label tweaks not worth their own bullet
- Bug fixes that are too narrow or edge-case to be meaningful to most users

### Always include (never collapse) — server releases only

Feature flags that are **fully removed** from the server codebase in this release. Flag removal is the moment self-hosted users gain access to a feature. Write each removal as a user-facing line describing what the feature does — not the internal flag identifier. See Step 4 for format.

### Investigate — flags enabled without a matching release issue

For every flag the Slack thread lists as **enabled**, check whether any issue gathered in Step 1a references it. If none do, the underlying work may have shipped in an earlier release and is only now going live (reportable), or it may guard an internal refactor or infrastructure change that was never going to be user-facing (collapses like any other item in that category).

Resolve what the flag guards, in this order:

1. Search Jira for the flag identifier as free text, without restricting to this release's `fixVersion` (e.g. `text ~ "flag-identifier" ORDER BY created ASC`), to find the ticket(s) that originally implemented the feature.
2. If a ticket is found, run its summary/description back through the Include / Collapse / Exclude filter above. Judge whether the guarded work itself is user-visible.
3. If nothing turns up, or if `search_issues` is unavailable, ask the user for a one-line description of what the flag enables, and classify that description the same way — do not guess or invent functionality.

If the filter says it's user-facing, write a plain-language line about the feature going live (Step 4 format rules). If the filter says it collapses or excludes, let it fall into the catch-all line or drop it, same as any other item in that category.

### Exclude entirely

- Security fixes, unless the Slack thread or the user explicitly approves specific wording for one (default to excluding all security fixes from named bullets)
- Internal tooling changes with zero user impact
- Duplicate or reverted changes

## Step 4: Write the Release Notes

### Format rules

- **Plain text only** — no markdown, no asterisks, no headers, no bullet characters
- One line per notable change
- Begin each line with a past-tense action verb: `Added`, `Updated`, `Fixed`, `Improved`, `Removed`
- Write from the **user's perspective** — what did they gain, lose, or notice?
- No Jira ticket numbers, no internal terminology, and critically: **no feature flag identifiers**
- Keep each line under ~12 words
- Aim for **3–7 notable bullet points** maximum, followed by one catch-all line
- End with: `Various under-the-hood improvements and minor bug fixes`

### Tone

Informative, brief, benefit-forward. Avoid marketing superlatives ("exciting", "powerful"). Avoid engineering jargon ("refactored", "migrated", "scaffolded", "deprecated"). Write for a non-technical user who wants to know if anything changed that affects them.

### Server flag removals

Flag removal lines describe **the feature the flag was guarding**, in plain user-facing language. Look up the associated Jira ticket, Confluence page, or Slack thread description to find the right framing. The internal flag name is a lookup key only — it never appears in the output.

Use the format:

```
Removed feature flag for [user-facing description of what the feature does]
```

Example: a flag named `pm-36859-refactor-org-collections-vault-component` becomes:

```
Removed feature flag for organization vault collection management improvements
```

Self-hosted users are the primary audience for this line — they are receiving the feature for the first time when the flag is removed, so the description should communicate the benefit clearly.

### Flags enabled for previously-shipped work

When a flag in the Slack thread's **enabled** list has no matching issue in this release, and the Step 3 investigation shows the guarded work is genuinely user-facing, write a normal named bullet describing the feature going live — phrased the same as any other `Added`/`Updated` line. Do not call out that it was "previously shipped" or reference the flag mechanics; users only care that the feature is now available to them.

Example: the Slack thread lists `pm-40021-item-share-preview` as enabled, but every issue tagged with that flag shipped two releases ago and none appear in this release's Jira list. A Jira search for the flag identifier turns up the original ticket, "Add preview before sharing vault items" — a user-facing change, so it earns a bullet. The resulting line:

```
Added a preview step before sharing vault items
```

Not every enabled flag reaches this point. If the same investigation instead turns up a ticket like "Refactor vault item sharing internals behind a flag," it collapses into the catch-all line exactly as it would have if it had shipped with a ticket in this release.

### Example output (clients release)

```
Updated UI for centralized ownership policy
Added a product tour for access intelligence
Added information banner to SCIM setup page
Added a checkout success page following Stripe payment flows
Various under-the-hood improvements and minor bug fixes
```

### Example output (server release with flag removals)

```
Added support for flexible collection permissions for enterprise plans
Improved admin console filtering for large organizations
Removed feature flag for flexible collection permission management
Removed feature flag for bulk collection management improvements
Various under-the-hood improvements and minor bug fixes
```

## Step 5: Review and Calibrate

Before presenting the final output, check:

- [ ] Every named bullet has its corresponding feature flag enabled in the Slack thread (or has no flag)
- [ ] Every flag in the Slack thread's enabled list has been checked against this release's Jira issues
- [ ] Any flag with no matching issue was resolved by lookup or by asking the user, then given a bullet, collapsed, or excluded
- [ ] No internal or infrastructure-only changes appear as named bullets
- [ ] Server releases include a line for every flag removal mentioned in the Slack thread, written in user-facing language
- [ ] No internal flag identifiers appear anywhere in the output
- [ ] Total named bullets are between 3 and 7 (if more than 7 are equally important, consolidate similar items)
- [ ] The catch-all line is present
- [ ] No markdown formatting in the output text