Release note generator
npm install @definitely-not-devs/notegenGenerate release notes from git commit history.
``bashWith npm
npm install --save-dev @definitely-not-devs/notegen
$3
`bash
With npm
npm install -g @definitely-not-devs/notegenWith pnpm
pnpm add -g @definitely-not-devs/notegenWith yarn
yarn global add @definitely-not-devs/notegen
`With global installation, use
notegen directly without npx.Quick Start
1. Initialize configuration:
`bash
npx notegen init
`This creates a
notegen.json file in your project:`json
{
"baseUrl": "https://jira.company.com/browse",
"releaseNotes": true,
"output": "CHANGELOG.md"
}
`2. Generate release notes:
`bash
npx notegen generate
`Usage
$3
`bash
Generate release notes for all commits
npx notegen generateOr add to package.json scripts:
{
"scripts": {
"release-notes": "notegen generate"
}
}Then run:
pnpm release-notes
`$3
`bash
Specify output file
npx notegen generate -o CHANGELOG.mdGenerate for specific commit range
npx notegen generate --from v1.0.0 --to v2.0.0Generate for a specific tag (auto-detects previous tag)
npx notegen generate --to v2.0.0Generate for the latest tag (auto-detects last and previous tag)
npx notegen generate --last --release-notesLimit number of commits
npx notegen generate --limit 10Generate release notes format (grouped by feat/fix with tickets)
npx notegen generate --release-notesWith ticket links
npx notegen generate --release-notes --base-url https://jira.company.com/browseGroup all versions under a single release tag
npx notegen generate --release-notes --group v2.0.0Useful for combining multiple tags into one production release
npx notegen generate --from v1.0.0 --to HEAD --group PROD-v2.0.0 --release-notes
`Options
-
-o, --output - Output file path (default: RELEASE_NOTES.md)
- -f, --from - Start from commit/tag (exclusive)
- -t, --to - End at commit/tag (inclusive, default: HEAD)
- -l, --limit - Limit number of commits
- -r, --release-notes - Generate release notes format with grouped tickets (feat/fix)
- --no-release-notes - Generate standard changelog format (overrides config)
- -b, --base-url - Base URL for linking tickets
- --last - Generate release notes for the last tag (auto-detects previous tag)
- -g, --group - Group all sections under a specific tag/version (useful for combining multiple tags into one release)
- -p, --print - Print output to console instead of writing to fileCLI options override configuration file settings.
Commit Processing
$3
Commits are processed in reverse chronological order (newest to oldest). This ensures the most recent changes appear first in your release notes.
$3
The tool automatically handles revert commits to keep your release notes accurate:
How it works:
1. Detects revert commits - Identifies commits starting with "Revert" or "revert"
2. Extracts reverted tickets - Finds ticket references (US-123, BUG-456, etc.) in the revert commit
3. Removes earlier commits - Filters out commits with those ticket IDs that came _before_ the revert
4. Preserves newer commits - Keeps commits with the same ticket ID if they came _after_ the revert
Example timeline:
`bash
Commit history (oldest to newest)
git commit -m "feat: add feature US-123" # ✗ Will be removed
git commit -m "Revert: feat US-123" # ✗ Revert itself removed
git commit -m "feat: re-add feature US-123" # ✓ Kept (after revert)
`Result: Only the final implementation of US-123 appears in release notes.
Supported revert formats:
`bash
Standard git revert
Revert "feat: add feature US-123"Manual revert with ticket in message
revert: remove feature US-123Revert with ticket in body
Revert "feat: add feature"US: 123
`This prevents duplicate or incorrect entries when features are reverted and re-implemented.
$3
All release notes are automatically grouped by version tags. The tool uses
git describe to associate each commit with its nearest reachable tag.How it works:
1. For each commit, the tool finds the most recent tag that contains it
2. Commits are grouped by version first, then by section type
3. Versions are sorted from newest to oldest
4. Commits without tags appear under "Untagged"
Example structure:
`markdown
2.0.0
$3
- US 1
- US 2
$3
- BUG 1
- BUG 2
1.9.0
$3
- US 3
- US 4
$3
- BUG 3
- BUG 4
`This structure makes it easy to see what changed in each version and generate release notes for specific releases.
#### Grouping Multiple Tags
When deploying to higher environments (e.g., production), you may have multiple tags but want to generate a single release note. Use the
--group flag:`bash
Combine multiple dev/staging tags into one production release
npx notegen generate --from v1.5.0 --to HEAD --group PROD-v2.0.0 --release-notes
`Example output:
`markdown
PROD-v2.0.0
$3
- US 1
- US 2
- US 3
- US 4
$3
- BUG 1
- BUG 2
- BUG 3
- BUG 4
`Instead of separating by individual version tags (2.0.0, 1.9.0), all commits are grouped under the specified tag.
Modes
$3
Groups commits by conventional commit prefixes and scopes, organized by version:
`bash
feat(api): add user authentication
fix(ui): resolve login bug
chore: update dependencies
`Generates a hierarchical changelog grouped by version:
`markdown
2.0.0
$3
#### api
- add user authentication
#### ui
- update dashboard
$3
#### api
- resolve login bug
1.0.0
$3
#### core
- initial release
`Commits are grouped by version first (detected from git tags), then by type (feat/fix/other), then by scope. Commits without a scope appear under "Other". Commits without a version tag appear under "Untagged".
Custom sections from config are not used in basic mode.
If your config has
"releaseNotes": true by default, you can override it with --no-release-notes to use basic mode.$3
Groups commits by ticket references for tracking, organized by version. The ticket reference can be in either the commit message or body:
`bash
In commit message (single -m)
git commit -m "feat: add user authentication US-123"
``bash
In commit footer (multiple -m or editor)
feat: add user authenticationUS: 123
``bash
fix: resolve login bugBUG: 456
`In release notes mode, commits are grouped by version first (detected from git tags), then by ticket reference type (
US, BUG, etc.).Supported ticket formats:
- Numeric:
US123, US 123, US-123, US:123, US#123
- Alphanumeric: JIRA-ABC-123, BUG_456, US-2024-789
- Multiple tickets per commit: US 234 & BUG 456 (each ticket gets its own line)
- Mixed types: US 234, BUG 456 (appears in both User Stories and Bugs sections)Requirements:
- Pattern must be a complete word (e.g.,
US won't match in FOCUS)
- Ticket ID must contain at least one digit
- Supports custom patterns defined in your configCommits without matching ticket references are excluded from release notes mode.
Custom Sections
You can configure custom sections in
notegen.json:`json
{
"sections": [
{
"section": "User Stories",
"pattern": "US",
"label": "US"
},
{
"section": "Bugs",
"pattern": "BUG",
"label": "BUG"
},
{
"section": "Improvements",
"pattern": "IMPROVEMENT",
"label": "IMPROVEMENT"
}
]
}
`Each section matches commits based on ticket references in either the commit message or body.
Pattern matching rules:
- The
pattern must match as a complete word (word boundaries enforced)
- Ticket IDs must contain at least one digit
- Flexible separators: space, dash, colon, or no separator
- Supports alphanumeric ticket IDs (e.g., JIRA-ABC-123)
- Multiple tickets in one commit will create separate entriesExample patterns:
-
US matches: US123, US-123, US 123, US:123, US#123, US-ABC-123
- BUG matches: BUG456, BUG-456, BUG_789
- Won't match: FOCUS 123 (US is not a complete word), US for (no digit)Practical Examples
$3
Git History:
`bash
git commit -m "feat: add login feature" -m "US: 100"
git commit -m "fix: resolve auth bug" -m "BUG: 200"
git commit -m "feat: add dashboard" -m "US: 101"
git commit -m "Revert: fix auth" -m "BUG: 200" # Reverting BUG-200
git commit -m "fix: proper auth fix" -m "BUG: 200" # Re-implementing BUG-200
`Command:
`bash
npx notegen generate --release-notes
`Output (RELEASE_NOTES.md):
`markdown
RELEASE NOTES
Generated: 2024-01-15
2.0.0
$3
- US 100
- US 101
$3
- BUG 200
---
Total: 3 item(s)
`What happened:
- Original BUG-200 fix was removed (reverted)
- Revert commit itself was removed
- New BUG-200 fix is kept (after revert)
- All US items kept (not reverted)
$3
Git History:
`bash
git commit -m "feat(auth): implement OAuth US-500"
git commit -m "feat(auth): add token refresh US-500"
git commit -m "fix(auth): handle edge case US-500"
git commit -m "Revert feat: OAuth not ready" -m "US: 500"
git commit -m "feat(api): add REST endpoints US-501"
git commit -m "feat(auth): implement SAML US-500" # New approach
`Command:
`bash
npx notegen generate --release-notes --base-url https://jira.company.com/browse
`Output:
`markdown
RELEASE NOTES
Generated: 2024-01-15
3.0.0
$3
- US 500
2.5.0
$3
- US 501
---
Total: 2 item(s)
`What happened:
- First 3 commits with US-500 removed (OAuth implementation reverted)
- US-501 kept (different ticket)
- Final US-500 commit kept (SAML implementation after revert)
$3
Git History:
`bash
git commit -m "feat: combined feature" -m "US: 600\nUS: 601"
git commit -m "fix: combined fixes" -m "BUG: 700\nBUG: 701"
git commit -m "Revert: feature not ready" -m "US: 600" # Only revert US-600
`Output:
`markdown
RELEASE NOTES
Generated: 2024-01-15
1.5.0
$3
- US 601
$3
- BUG 700
- BUG 701
---
Total: 3 item(s)
`What happened:
- US-600 removed (reverted)
- US-601 kept (same commit, but different ticket - not reverted)
- All bug fixes kept (not reverted)
$3
Command:
`bash
npx notegen generate --from v1.0.0 --to v2.0.0 --release-notes
``Only processes commits between v1.0.0 and v2.0.0, applying revert logic within that range. Reverts outside the range don't affect commits inside the range.