Change log

Quorum Plus Release Notes Format

Purpose

Release notes tell users what changed, what got better, what got fixed, and what to watch out for. They land in three places:

1. In-product release notes surface (planned for v1.x, not yet shipped). Users see a short version inside Quorum Plus, time-anchored.
2. Public release notes page at quorum.app/releases (planned). The canonical human-readable record.
3. Developer changelog at CHANGELOG.md in the quorum-app repo. The technical record, one entry per PR or meaningful commit group.

This doc specifies the voice and structure of (1) and (2) — the human-readable release notes. (3) is a separate technical changelog that Paige owns independently; it can be denser and more literal.

Ownership (Model B)

Decided 2026-04-23.

• Paige (Tech Writer) drafts the human-readable release notes from the git log + sprint-status.yaml entries for the release window. She owns technical accuracy (did the thing actually ship? does the description match what got built?).
• Quentin (Content Strategist) runs a voice pass on every draft before publish. I own voice, tone, reading level, accessibility phrasing, and AI-tell avoidance.
• Paige publishes after my voice pass lands.

If marketing surface grows later (dedicated "What's new" page, email campaigns per release), Model A becomes the natural split: user-facing release notes owned by Quentin end-to-end, developer changelog stays with Paige. That's not where we are in v1.

Release types and their voice

Template

Every release note follows this structure. Sections that don't apply are omitted entirely (don't write "No fixes this release"). Sections always appear in this order.

---
version: X.Y.Z
date: YYYY-MM-DD
type: major | minor | patch | hotfix
---

# [Short release title in sentence case]

[Optional one-paragraph intro. Major and minor only. Skip for patch and hotfix.]

## What's new

- **[Feature name]**: [One-sentence description of what it does and what it unblocks.]
- **[Feature name]**: [Same pattern.]

## What we improved

- **[Area]**: [What got better and how users feel the difference.]

## What we fixed

- [Bug, user-visible if possible.] No more "resolved an issue." Be specific: what was broken, what works now.

## Known issues

- [Anything users may hit that we haven't resolved, with a workaround if one exists.]

---

*[Optional closing line. Sincere, short. See voice rules.]*

Voice rules

Release notes are customer-facing content. The full voice-tone-guide applies, including:

• No em dashes. Use colons, parentheses, periods.
• No AI-tell blacklist words or phrases ("paradigm," "holistic," "leverage," "seamlessly," "unlock," "it's important to note," "let's dive into," etc.).
• Active voice. "We shipped X" or "X now does Y." Not "X has been shipped" or "We're happy to announce X."
• No hype. "Shipped," "added," "improved," "fixed." Not "thrilled to announce," "proudly released," "game-changing."
• Specific over abstract. Name the thing. Name the screen. Name the number. Not "various improvements" or "several fixes." If there were 12 small fixes, list them or say "twelve small fixes across [area]."
• Grade 9 reading level per NFR-A4.
• No exclamation points unless genuine urgency or rare celebration. "Welcome to v2.0." Not "Welcome to v2.0!"

What belongs in each section

What's new. Capabilities that weren't there before. User-visible features only. Internal refactors don't go here.

What we improved. Existing things that work better. Performance, clarity, speed, fewer steps, better defaults.

What we fixed. Bugs users experienced or could have experienced. Name the symptom the user saw, not the internal cause. "Invitation emails weren't landing in some inboxes. They do now." Not "Fixed invitation email SMTP relay retry logic."

Known issues. Things that may still hit the user. Include a workaround if one exists. Don't hide known issues; users find them and lose trust if we pretend they don't exist.

What doesn't belong

• Internal refactors, dependency bumps, CI changes, test additions. Put those in the developer changelog (CHANGELOG.md), not the user-facing release notes.
• Marketing claims ("the best," "unprecedented," "revolutionary"). Don't.
• Roadmap teasers ("coming soon," "stay tuned for..."). Release notes describe what shipped, not what's next.
• Apologies for bugs. "We fixed X" is honest. "We're so sorry X was broken" reads panicked.

Cadence

• Major and minor releases: Published within 24 hours of the build hitting production.
• Patches: Published the same day as the ship.
• Hotfixes: Published within 1 hour of the fix landing in production, concurrent with any status-page update.

Paige drafts in a markdown file under _bmad-output/release-notes/vX.Y.Z.md in the quorum-app repo. She flags me for voice pass. I return a voice-cleaned version same-day. Paige publishes.

Worked examples

Example 1: patch release

---
version: 1.0.3
date: 2026-05-08
type: patch
---

# Sign-in reliability fixes

## What we fixed

- Sign-in with Apple occasionally looped back to the start on Safari iOS 17. Now lands in the workspace on the first try.
- Invitation emails sent to Gmail addresses sometimes took 10+ minutes to arrive. Average arrival is now under 30 seconds.
- Workspace settings page didn't load for users with more than 50 pending invites. It does now.

## Known issues

- Workspace creation from an invite still shows a blank spinner for up to 4 seconds on very slow connections. Fix in progress for v1.0.4.

Example 2: minor release

---
version: 1.2.0
date: 2026-06-19
type: minor
---

# Export presets and bulk invites

## What's new

- **Export presets.** Save a custom PDF, DOCX, or HTML export configuration once and apply it to any artifact with one click. Presets live per workspace.
- **Bulk team invites.** Paste a list of email addresses into the invite field (comma, newline, or tab-separated). Quorum Plus sends them all with the role you pick.

## What we improved

- **Pipeline rail clarity.** The active step now shows the agent working on it in the rail label, not just in the center panel. Faster to re-orient when you're scrolling the transcript.
- **Sprint status export speed.** Generating the Sprint Status HTML export from a full 12-epic board is now about 3× faster.

## What we fixed

- Portfolio document PDF export sometimes dropped the cover-page title on very long project names. Titles over 80 characters now wrap cleanly.
- Dispute mode on the three-pillar filter occasionally showed Solo plan users the enterprise-only "Request agent trace" button. The button is now gated correctly.

Example 3: hotfix

---
version: 1.1.2-hotfix.1
date: 2026-06-02
type: hotfix
---

# Security fix for workspace invitation tokens

## What we fixed

Invitation tokens for new workspace members were not being invalidated after use in a small number of cases. This meant a used invitation link could, in theory, be clicked a second time by the same user without re-authenticating. No external exposure detected in the audit. The fix invalidates tokens atomically on first accept and re-confirms every subsequent access.

If you received an invitation link recently and it now returns a "Link expired" message, ask your workspace owner to send a new one.

Pre-publish checklist (Paige's)

Before flagging me for voice pass, confirm:

• [ ] Version number matches the build that shipped.
• [ ] Date is the actual ship date, not the draft date.
• [ ] Every bullet describes something a user can observe. No internal refactors in user-facing sections.
• [ ] "What's new" capabilities are linked to at least one PR or sprint-status story entry.
• [ ] "What we fixed" bullets describe the user-facing symptom, not the internal cause.
• [ ] Known issues include workarounds where workarounds exist.
• [ ] No em dashes. No blacklisted words. No hype. No apologies.

My voice-pass checklist (Quentin's)

When a release note reaches me:

• [ ] Read start-to-finish for voice drift (em dashes, blacklist words, hype, hedging).
• [ ] Check every bullet for "we fixed an issue" vagueness → require specific symptom.
• [ ] Check reading level. Grade 9 or below. Technical terms allowed where accurate; avoid jargon where plain words work.
• [ ] Check tone against release type (major = forward-looking; patch = matter-of-fact; hotfix = brief and calm).
• [ ] Confirm closing line, if present, reads sincere and short.
• [ ] Return annotated markdown diff to Paige with changes + rationale for non-obvious edits.

Living doc

This format updates as we learn from real releases. First real release note cut against this template adds to the examples section. Pattern deviations that land well update the template. Pattern deviations that land poorly get logged in a "what not to do" section.

Change log