Changelog Command

The nanx repo change-log command (alias: nanx r clog) provides comprehensive changelog management including generation, listing, viewing, and validation.

Quick Start

# Generate a changelog for the current version
nanx r change-log generate my-project

# Generate changelog for a specific version (auto-resolves from/to)
nanx r change-log generate my-project --version 1.2.0

# List all changelogs for a project
nanx r change-log list my-project

# Show the latest changelog
nanx r change-log show my-project

# Validate changelog structure
nanx r change-log validate my-project

Subcommands

generate (alias: g)

Generate a changelog for a specific version or all missing versions:

# Basic generation (interactive)
nanx r change-log generate my-project

# Generate for specific version range
nanx r change-log generate my-project --from v1.0.0 --to v1.1.0

# Generate all missing changelogs
nanx r change-log generate my-project --all-missing

# Non-interactive with specific format
nanx r change-log generate my-project --format keep-a-changelog --no-interactive

# Preview without writing files
nanx r change-log generate my-project --dry-run

Options

list (alias: ls)

List existing changelogs for a project or all projects:

# List all changelogs for a project
nanx r change-log list my-project

# List only end-user changelogs
nanx r change-log list my-project --end-user

# List only internal changelogs
nanx r change-log list my-project --internal

# List changelogs for all projects
nanx r change-log list

Options

show (alias: s)

Display a specific changelog file:

# Show latest changelog
nanx r change-log show my-project

# Show specific version
nanx r change-log show my-project v1.2.0

# Show end-user version
nanx r change-log show my-project v1.2.0 --end-user

# Output raw markdown
nanx r change-log show my-project --raw

# Don't use pager
nanx r change-log show my-project --no-pager

Options

validate (alias: v)

Validate changelog file structure and content:

# Validate all changelogs for a project
nanx r change-log validate my-project

# Validate specific version
nanx r change-log validate my-project v1.2.0

Validation checks:

• Markdown structure - Valid markdown with headers
• Version header - Matches the filename version
• Required sections - Statistics and Contributors for internal changelogs

paths

Show changelog paths and configuration for a project:

nanx r change-log paths my-project

Output includes:

• Project root path
• Changelog directory path
• End-user directory path
• Internal format
• End-user format
• Tag prefix
• AI provider (if configured)

Changelog Formats

nanx supports multiple changelog formats to match your project's style:

Dual Changelog Generation

By default, nanx generates two types of changelogs:

• Internal/Technical - Detailed implementation notes with code locations, statistics, and contributor info
• End-User - User-friendly summary focusing on features, improvements, and bug fixes

Output structure:

my-project/
  change-logs/
    v1.0.0.change-log.md      # Internal changelog
    v1.1.0.change-log.md
    end-user/
      v1.0.0.change-log.md    # End-user changelog
      v1.1.0.change-log.md

Custom Rules

Create a custom rules file to define your own changelog format. Use the @extends directive to build on existing formats:

# .ai/changelog-rules.md

# @extends detailed-changelog

## Custom Rules

- Always include issue links in format [#123](url)
- Group changes by component/module
- Include migration notes for breaking changes
- Add "Known Issues" section when applicable

Supported @extends values:

• detailed / detailed-changelog
• keep-a-changelog / kac
• conventional / conventional-changelog

Configuration

Configure changelog generation in your .repo.yml:

Repository-Level Configuration

# .repo.yml
release:
  changelog:
    enabled: true
    output_dir: "change-logs"
    end_user_dir: "end-user"
    internal_format: "detailed"
    end_user_format: "detailed"
    include_contributors: true
    end_user_show_contributors: true
    end_user_include_emails: false
    issue_url_template: "https://linear.app/myorg/issue/{id}"
    rules_file: ".ai/changelog-rules.md"
    provider: "anthropic"
    team_name: "My Team"
    changelog_public_url_base: "https://docs.example.com/changelogs"
    tag_message_contributor_format: "name"  # or "full"
    fallback_on_ai_error: false  # Set to true to auto-fallback on AI errors

Per-Project Overrides

# .repo.yml
release:
  projects:
    my-lib:
      changelog:
        internal_format: "keep-a-changelog"
        provider: "openai"
      changelog_include_dependencies: true
      changelog_include_paths:
        - "libs/shared"
      changelog_exclude_paths:
        - "libs/test-utils"
        - "**/*.test.ts"

Configuration Options

Integration with Release Command

The changelog command integrates with nanx repo release. During a release, changelogs can be generated automatically:

# Release with automatic changelog generation
nanx repo release

# Skip changelog generation
nanx repo release --no-changelog

# Use specific format
nanx repo release --changelog-format keep-a-changelog

# Skip end-user changelog
nanx repo release --no-end-user-changelog

# Use existing changelog if found
nanx repo release --use-existing-changelog

# Force regeneration even if changelog exists
nanx repo release --regenerate-changelog

See Release Workflow for more details on the pause/continue workflow for changelog review.

Examples

Generate Changelog for New Release

# Stage and commit your changes
nanx r aa && nanx r cgm

# Generate changelog before release
nanx r change-log generate my-project --version v1.3.0

# Review the generated changelog
nanx r change-log show my-project v1.3.0

# If satisfied, create the release
nanx repo release --use-existing-changelog

Backfill Missing Changelogs

# Generate changelogs for all versions that don't have one
nanx r change-log generate my-project --all-missing

# Validate all generated changelogs
nanx r change-log validate my-project

CI/CD Integration

# Non-interactive changelog generation for CI
nanx r change-log generate my-project \
  --from v1.2.0 \
  --to v1.3.0 \
  --version v1.3.0 \
  --format detailed \
  --no-interactive

Troubleshooting

AI Generation Failed New in v0.4.1

If AI changelog generation fails, you'll see a helpful error message with options:

# Option 1: Use commits-only format (no AI needed)
nanx r change-log generate my-project --format commits-only

# Option 2: Enable automatic fallback in .repo.yml
# release:
#   changelog:
#     fallback_on_ai_error: true

# Option 3: Fix the AI provider issue
nanx config show | grep -A 10 providers

AI Provider Not Found

# Check configured providers
nanx config show | grep -A 10 providers

# Set provider for changelog
nanx r change-log generate my-project --provider anthropic

No Tags Found

# List available tags
git tag -l

# Specify range manually
nanx r change-log generate my-project --from abc123 --to HEAD --version v1.0.0

Changelog Not Generated

# Use dry-run to debug
nanx r change-log generate my-project --dry-run

# Check paths configuration
nanx r change-log paths my-project

Next Steps

• Repository Commands
• Release Workflow
• Repository Config Reference
• AI Providers Setup
• View nanx Changelogs