changenotes

Lightweight changelog management - version agnostic, prerelease friendly.

Why changenotes?

| Tool | Problem | |------|---------| | Changesets | Tied to semver, monorepo-focused, rigid workflow | | semantic-release | Requires Conventional Commits, fully automated (no human control) | | release-it | Full release tool, not just changelog |

changenotes focuses only on changelog management:

• Works with any version format (semver, calver, date-based, etc.)
• Supports prerelease (beta/rc) workflows with auto-detection
• CLI + API for easy integration
• No opinions on how you publish

Install

npm install changenotes

Quick Start

# Initialize in your project
changenotes init

# Add changes during development
changenotes add -t feat -m "Add new feature"
changenotes add -t fix -m "Fix bug" -s runtime

# List pending changes
changenotes list

# Preview changelog
changenotes preview

# Release beta (auto-detected from version)
changenotes release 1.2.0-beta.1

# Release stable
changenotes release 1.2.0

# Release stable and merge all previous beta entries
changenotes release 1.2.0 --squash-pre

CLI Commands

changenotes add

Add a new change entry. Interactive mode if no options provided.

changenotes add                              # Interactive
changenotes add -t feat -m "Add feature"     # Quick add
changenotes add -t fix -m "Fix bug" -s api   # With scope
changenotes add -t feat -m "New API" -b      # Breaking change
changenotes add -t fix -m "Fix #123" -i "#123"  # With issue

Options:

• -t, --type: Change type (feat|fix|perf|refactor|docs|style|test|chore)
• -m, --message: Change summary
• -s, --scope: Optional scope
• -b, --breaking: Mark as breaking change
• -i, --issue: Related issue (repeatable)

changenotes list

List all unreleased changes.

changenotes preview

Preview the changelog output.

changenotes preview           # Markdown, grouped by type
changenotes preview --json    # JSON format
changenotes preview --flat    # Flat list, not grouped

changenotes release <version>

Release changes to CHANGELOG.md. Prerelease is auto-detected from version string.

changenotes release 1.2.0-beta.1        # Beta (auto-detected)
changenotes release 1.2.0-rc.1          # RC (auto-detected)
changenotes release 1.2.0               # Stable release
changenotes release 1.2.0 --squash-pre  # Stable + merge all prereleases
changenotes release 1.2.0 --no-clear    # Don't clear change files
changenotes release 1.2.0 --date 2024-01-15  # Custom date

Options:

• --squash-pre: Merge previous prerelease entries into this stable release
• --no-clear: Don't clear change files after release
• --date: Custom release date (default: today)

changenotes clear

Clear all change files.

changenotes init

Initialize changenotes in the current directory.

Programmatic API

import { createChangenotes } from 'changenotes';

const cn = createChangenotes(process.cwd());

// Add a change
cn.add({
  type: 'feat',
  summary: 'Add new feature',
  scope: 'api',
  breaking: false,
  issues: ['#123'],
});

// List changes
const changes = cn.list();

// Preview
const markdown = cn.preview({ format: 'markdown', groupByType: true });

// Release (prerelease auto-detected from version)
cn.release({ version: '1.2.0-beta.1' });

// Release stable with squash
cn.release({ version: '1.2.0', squashPrerelease: true });

// Release with options
cn.release({
  version: '1.2.0',
  date: '2024-01-15',
  clearAfter: true,
  squashPrerelease: false,
});

Configuration

Create .changenotesrc.json or add changenotes field to package.json:

{
  "changeDir": ".changes",
  "changelogFile": "CHANGELOG.md",
  "types": ["feat", "fix", "perf", "refactor", "docs", "style", "test", "chore"],
  "repoUrl": "https://github.com/user/repo"
}

Workflow Example

Development Phase

# Developer A adds a feature
changenotes add -t feat -m "Add user authentication"

# Developer B fixes a bug  
changenotes add -t fix -m "Fix login redirect" -s auth

# Changes are stored as individual files in .changes/

Beta Releases

# Release beta 1 (writes to CHANGELOG.md, clears .changes/)
changenotes release 2.0.0-beta.1

# More development...
changenotes add -t fix -m "Fix issue found in beta"

# Release beta 2
changenotes release 2.0.0-beta.2

Stable Release

# Option A: Just release (keeps beta entries separate in CHANGELOG)
changenotes release 2.0.0

# Option B: Squash betas (removes beta entries, merges into 2.0.0)
changenotes release 2.0.0 --squash-pre

License

MIT