Changelog Convention

This is the contract for writing and maintaining the project changelog. The changelog is a public-facing document — it must be understandable by both technical and non-technical readers.

Principles

#	Principle	Meaning
C1	Change + Impact	Every entry states what changed AND what it means for the user
C2	Date-based, not version-based	SaaS ships continuously — dates are the natural grouping
C3	Newest first	Most recent date at the top of the file
C4	No merge commits	Only meaningful changes — merge commits are noise
C5	No internal chores	Scaffolding, refactors, CI tweaks, and doc reformats do not belong here
C6	Plain language	No function names, file paths, class names, or code snippets
C7	One line per change	Bold the feature/area, dash, then the impact — keep it scannable

Format

## {Month Day, Year}

### {Category}

- **{Feature/Area}** — {What changed and why it matters} <Badge type="{tip|info|warning|danger}" text="{area}" />

The <Badge> at the end is a VitePress component that renders as a colored pill. The type is dictated by the category (see Badge Types), and the text must come from the Area Map.

Badge Types

The badge type is fixed per category — readers get an at-a-glance signal of what kind of change they're looking at, regardless of the area tag.

Category	Badge type	Color	Intent
New	`tip`	green	Net-new capability — something the user can now do
Improved	`info`	blue	Refinement of existing behaviour — faster, clearer, or smoother
Fixed	`info`	blue	Bug fix with user-visible impact
Breaking	`warning`	yellow	Action required — see the Breaking callout
Removed	`danger`	red	Feature or surface taken away
Security	`danger`	red	Security patch — disclosed when safe

Examples:

<Badge type="tip" text="auth" /> — new auth capability
<Badge type="info" text="billing" /> — billing improvement or fix
<Badge type="warning" text="auth" /> — breaking auth change
<Badge type="danger" text="auth" /> — removed auth surface or security patch

Category	When to use	Example
New	New feature, endpoint, or capability	Workspace invites — invite members by email with role selection
Improved	Enhancement to existing behavior	Token refresh — 40% faster due to optimized fingerprint lookup
Fixed	Bug fix with user-visible impact	Google OAuth — no longer fails when profile picture URL is missing
Breaking	API contract change, migration required	Auth header — `X-Auth-Token` replaced with standard `Authorization: Bearer`
Security	Security patch (only when safe to disclose)	Password reset — all active sessions are now revoked on password change
Removed	Deprecated feature removed	Legacy API — v1 endpoints have been removed

Area Map

Every changelog entry must end with an area tag. Use one from this list. If a change doesn't fit, add a new area here first.

Area	Scope
`auth`	Authentication, login, OAuth, tokens, sessions, cookies
`identity`	User profiles, onboarding, account verification, password reset, OTP, multi-tenant sign-in
`logs`	Audit logs, system events, traceability
`platform`	Server bootstrap, middleware, request context, error handling, feature flags, runtime stability
`security`	Rate limiting, lockouts, token rotation, data protection, permission framework, role evaluation
`dx`	Developer experience, docs site, onboarding tour, shortcuts, changelog
`content`	Content management, content sections (venue, schedule, linear, collection, game, VOD, badge), uploads, content search and filtering
`brand`	Brand themes, theme management, fonts, typography, brand publishing
`template-builder`	Template builder pages, routes, and supporting service
`appcms`	AppCMS settings, configuration, file upload and save
`command-center`	Command Center launcher, keyboard navigation, search integration
`customer-support`	Customer support detail, search, billing visibility, refunds, subscription actions, session handling
`dashboard`	Overview dashboard, widgets (team work, your work, video errors, quick actions)
`navigation`	Sidebar, breadcrumbs, route visibility, organization switching

Rules

Group by date — use ## {Month Day, Year} as the heading (e.g., ## April 3, 2026)
One entry per user-visible change — internal restructuring is not a changelog entry
Bold the subject — the feature or area name is always bold at the start of the line
Impact is mandatory — never write just "added X". Always state what it enables or fixes
No merge commits — merge commits are excluded; only direct, meaningful changes are logged
No commit hashes — this is a product changelog, not a git log
Aggregate related commits — multiple commits that build one feature become a single entry
Tag with category-coloured area badge — every entry ends with a <Badge> whose type is fixed by the category (see Badge Types) and whose text is an Area Map value. Example: a New auth feature uses <Badge type="tip" text="auth" />; a Fixed billing bug uses <Badge type="info" text="billing" />.
Breaking changes get a callout — in addition to the badge, use a VitePress warning container for breaking changes:
```
::: warning Breaking
**{Area}** — {What changed and what action is needed}
:::
```

What Belongs vs. What Doesn't

Belongs	Does NOT belong
New endpoint or feature	Scaffolding or boilerplate
Behavior change users will notice	Internal refactors
Bug fix with user-facing symptom	Test additions or CI changes
Security patch	Doc formatting fixes
Breaking API change	Dependency bumps (unless breaking)
Performance improvement users feel	Code style changes

Timing

Update docs/changelog.md as part of any PR that introduces a user-visible change
Aggregate small changes from the same day into a single date entry
When generating a changelog from git history, filter out chore:, docs:, test:, and ci: prefixed commits unless they have user-visible impact

Changelog Convention