Changelog Maintenance for Nomos

This skill ensures consistent CHANGELOG.md updates following Keep a Changelog format and Semantic Versioning standards for the Nomos monorepo.

When to Use This Skill

After merging a PR that affects user-visible behavior
When creating or preparing a release
Reviewing changelog entries for correctness
Converting PR descriptions to changelog entries
Updating compare links after releases

Standards Overview

Format: Keep a Changelog (https://keepachangelog.com/en/1.1.0/)
Versioning: Semantic Versioning (https://semver.org/)
File: Root-level CHANGELOG.md (single source of truth)
Order: Newest release first; always maintain [Unreleased] section at top
Date format: YYYY-MM-DD (UTC)

Entry Categories (In Order)

Use only these categories in this exact order:

Added - New features
Changed - Changes in existing functionality
Deprecated - Soon-to-be removed features
Removed - Removed features
Fixed - Bug fixes
Security - Security fixes
Performance - Performance improvements

Adding Entries to Unreleased

Step 1: Map PR to Category

Label → Category mapping:

enhancement/feature → Added
bug/bugfix → Fixed
perf/performance → Performance
security → Security
refactor/chore → Changed (only if user-visible)
deprecate → Deprecated
remove → Removed
docs → Changed (only if affects public API/behavior)

If multiple labels: Pick most user-relevant category

Step 2: Determine Scope

Derive scope from file paths:

Examples:

apps/command-line/** → [CLI]
libs/compiler/** → [Compiler]
libs/parser/** → [Parser]
libs/provider-downloader/** → [Provider Downloader]
libs/provider-proto/** → [Provider Proto]
.github/** or docs/** → [Docs] or omit if internal-only

Optional sub-scope:

[CLI][Init] - for init command
[Compiler][References] - for reference resolution
[Parser][Errors] - for error handling

Step 3: Write Entry

Format:

- [Scope] Imperative description (#PR-number)
- [Scope][SubScope] BREAKING: Description (closes #issue)

Guidelines:

Use imperative mood ("Add", "Fix", "Improve", not "Added", "Fixed", "Improved")
Be concise and user-facing
Reference PR: (#123)
Reference issue: (closes #456) or (fixes #789)
Prefix breaking changes: BREAKING:
No trailing periods
Wrap code identifiers in backticks: Options.AllowMissingProvider

Examples:

### Added
- [CLI] Add `--allow-missing-provider` flag for graceful provider failures (#145)
- [Compiler] Add provider caching for deterministic builds (#152)

### Changed
- [Parser] BREAKING: Remove top-level `reference:` statements (closes #130)
- [Compiler] Improve error messages for unresolved references (#148)

### Fixed
- [CLI] Fix exit code for strict mode validation failures (#150)
- [Provider Downloader] Correct checksum validation for cross-platform binaries (#155)

### Performance
- [Compiler] Reduce reference resolution time by ~40% with cache (#160)

Step 4: Insert Entry

Ensure Unreleased exists:
```
## [Unreleased]
```
Find or create category:
```
## [Unreleased]

### Added
```

Add entry at top of category (newest first):

### Added
- [CLI] Add new feature (#NEW)  ← New entry here
- [Compiler] Previous feature (#OLD)

Maintain category order:
- Added
- Changed
- Deprecated
- Removed
- Fixed
- Security
- Performance

Creating a Release

Step 1: Determine Version Bump

SemVer rules:

MAJOR (X.0.0) - Breaking changes (API incompatibility)
MINOR (0.X.0) - New features (backward-compatible)
PATCH (0.0.X) - Bug fixes (backward-compatible)

Look for:

Any BREAKING: entries → MAJOR bump
Any Added entries without breaking → MINOR bump
Only Fixed, Performance, Security → PATCH bump

Nomos-specific versioning:

CLI: apps/command-line/v1.x.x (stable, MAJOR version)
Compiler: libs/compiler/v0.x.x (pre-1.0, MINOR breaking changes allowed)
Parser: libs/parser/v0.x.x (pre-1.0)

Step 2: Create Version Section

Add new section below Unreleased:

## [Unreleased]

## [1.2.0] - 2025-12-29

Move entries from Unreleased:

## [Unreleased]

## [1.2.0] - 2025-12-29

### Added
- [CLI] Add `--allow-missing-provider` flag (#145)

### Fixed
- [CLI] Fix exit code for strict mode (#150)

Keep Unreleased empty:

## [Unreleased]

## [1.2.0] - 2025-12-29

Step 3: Update Compare Links

At bottom of CHANGELOG.md:

Before release:

[Unreleased]: https://github.com/autonomous-bits/nomos/compare/v1.1.0...HEAD

After release v1.2.0:

[Unreleased]: https://github.com/autonomous-bits/nomos/compare/v1.2.0...HEAD
[1.2.0]: https://github.com/autonomous-bits/nomos/compare/v1.1.0...v1.2.0
[1.1.0]: https://github.com/autonomous-bits/nomos/compare/v1.0.0...v1.1.0

Pattern:

[Unreleased]: https://github.com/autonomous-bits/nomos/compare/v{LATEST}...HEAD
[{LATEST}]: https://github.com/autonomous-bits/nomos/compare/v{PREVIOUS}...v{LATEST}

Common Scenarios

Scenario 1: Adding Entry After PR Merge

Given: PR #145 merged adding --allow-missing-provider flag to CLI

Steps:

Identify category: Added (new feature)
Determine scope: [CLI]
Write entry: [CLI] Add \--allow-missing-provider` flag for graceful provider failures (#145)`
Add to Unreleased → Added section

Result:

## [Unreleased]

### Added
- [CLI] Add `--allow-missing-provider` flag for graceful provider failures (#145)

Scenario 2: Breaking Change

Given: PR #130 removes deprecated top-level reference: statements

Steps:

Identify category: Removed (removing feature)
Determine scope: [Parser]
Write entry: [Parser] BREAKING: Remove top-level \reference:` statements (closes #130)`
Add to Unreleased → Removed section

Result:

## [Unreleased]

### Removed
- [Parser] BREAKING: Remove top-level `reference:` statements (closes #130)

Scenario 3: Bug Fix

Given: PR #150 fixes CLI exit code bug

Steps:

Identify category: Fixed (bug fix)
Determine scope: [CLI]
Write entry: [CLI] Fix exit code for strict mode validation failures (#150)
Add to Unreleased → Fixed section

Result:

## [Unreleased]

### Fixed
- [CLI] Fix exit code for strict mode validation failures (#150)

Scenario 4: Preparing Release

Given:

Current version: v1.1.0
Unreleased has 2 Added, 1 Fixed
No breaking changes

Steps:

Version bump: MINOR (1.2.0) - has Added entries
Create section: ## [1.2.0] - 2025-12-29
Move all entries from Unreleased
Update compare links

Result:

## [Unreleased]

## [1.2.0] - 2025-12-29

### Added
- [CLI] Add `--allow-missing-provider` flag (#145)
- [Compiler] Add provider caching (#152)

### Fixed
- [CLI] Fix exit code for strict mode (#150)

[Unreleased]: https://github.com/autonomous-bits/nomos/compare/v1.2.0...HEAD
[1.2.0]: https://github.com/autonomous-bits/nomos/compare/v1.1.0...v1.2.0

Validation Checklist

Before committing changelog updates:

What NOT to Include

Exclude these from changelog:

Internal-only changes:
- CI configuration updates
- Test-only refactoring
- Internal tool updates
- Build script changes (unless affects users)
Non-user-visible changes:
- Code refactoring (unless API changed)
- Internal documentation
- Development dependencies
- Logging improvements
Sensitive information:
- Secrets or API keys
- Internal URLs or endpoints
- Security vulnerability details (until fixed)
- Personal information
Trivial updates:
- Typo fixes in comments
- Whitespace changes
- Code formatting

Multi-Module Releases

Nomos is a monorepo with independent module versioning:

Separate entries for separate modules:

### Added
- [CLI] Add `--timeout` flag (#145)
- [Compiler] Add reference caching (#152)

NOT grouped by module:

### CLI
- Add `--timeout` flag (#145)

### Compiler  
- Add reference caching (#152)

Reference Documentation

For complete changelog rules, see:

.github/instructions/changelog.instructions.md
Keep a Changelog: https://keepachangelog.com/en/1.1.0/
Semantic Versioning: https://semver.org/

changelog-maintenance

Changelog Maintenance for Nomos

When to Use This Skill

Standards Overview

Entry Categories (In Order)

Adding Entries to Unreleased

Step 1: Map PR to Category

Step 2: Determine Scope

Step 3: Write Entry

Step 4: Insert Entry

Creating a Release

Step 1: Determine Version Bump

Step 2: Create Version Section

Step 3: Update Compare Links

Common Scenarios

Scenario 1: Adding Entry After PR Merge

Scenario 2: Breaking Change

Scenario 3: Bug Fix

Scenario 4: Preparing Release

Validation Checklist

What NOT to Include

Multi-Module Releases

Reference Documentation