DOCSEARCHbyAlgolia
Submit Docs

changelogen

repository·main·Indexed 23 days ago

https://github.com/unjs/changelogen

A tool for generating automated changelogs based on Conventional Commits. It supports version bumping, git tagging, npm publishing, and GitHub release synchronization. The CLI provides workflows for displaying changelogs in the console, updating package.json and CHANGELOG.md, and performing full releases including git commits and tags.

Tokens
6.4K
Snippets
10
Records
37
Agent score
78%

What's inside changelogen

  1. Sync changelogen with GitHub Releases

    main

    Changelogen can automatically sync your local CHANGELOG.md with GitHub releases using the gh release command. This parses the current CHANGELOG.md (checking local then remote) to create or update releases on GitHub.

    Prerequisites:

    • A valid repository field must exist in package.json OR repo must be set in .changelogenrc.
    • For automation, you must provide a GitHub token.

    Authentication Methods:

    • Environment Variables: CHANGELOGEN_TOKENS_GITHUB, GITHUB_TOKEN, or GH_TOKEN.
    • CLI Argument: --token <token>.
    • Global Config: tokens.github=<token> in ~/.changlogenrc.
    • GitHub CLI: Use an authenticated session via gh auth login.

    If unauthenticated, the tool will attempt to open a browser link for manual release.

    npx changelogen@latest gh release [all|versions...] [--dir] [--token]

  2. Quick Start with changelogen

    main

    You can use npx changelogen@latest to generate changelogs based on Conventional Commits.

    Common workflows:

    • Display in console: Generate a Markdown changelog and print it to the terminal.
    • Bump version: Generate a changelog, update the version in package.json, and update CHANGELOG.md (without creating a git commit).
    • Full release: Bump the version, update CHANGELOG.md, and perform a git commit and tag.

  3. Configure changelogen

    main

    Configuration is handled via unjs/c12 and can be defined in several ways in your project root:

    • changelog.config.json
    • changelog.config.{ts,js,mjs,cjs}
    • .changelogrc
    • The changelog field within package.json

  4. Requirements for GitHub release command

    main

    To use the changelogen gh release command, your project configuration must meet the following requirements:

    1. Provider: The repo.provider in your changelog configuration must be set to "github".
    2. Changelog Content: The command requires a valid CHANGELOG.md (or the file specified in your output config) containing parsed releases with both a version and a body.
    3. Authentication: A GitHub token must be available. This can be provided via the --token CLI flag or configured in your project settings.

  5. Understand the GitCommit data structure

    main

    When commits are parsed using parseGitCommit, they are transformed from RawGitCommit into a GitCommit object. This structure follows the Conventional Commits specification.

    Key Fields:

    • type: The commit type (e.g., feat, fix).
    • scope: The scope of the change (mapped via config.scopeMap).
    • description: The cleaned commit message description.
    • isBreaking: Boolean indicating if the commit is a breaking change (detected via ! in the header or BREAKING CHANGE: in the body).
    • references: An array of Reference objects containing hash, issue, or pull-request types.
    • authors: An array of GitCommitAuthor objects, including the primary author and any co-authored-by entries found in the commit body.

  6. Perform version bumping with changelogen

    main

    changelogen can automatically determine the next version by inspecting Conventional Commits. You can either let it decide automatically or force a specific bump type.

    Automatic Bumping

    If --bump is passed, the tool analyzes commit types (e.g., feat, fix, breaking change) to decide if it should be a major, minor, or patch release.

    Manual Bump Types

    You can force a specific bump type using the following flags:

    • --major / --premajor
    • --minor / --preminor
    • --patch / --prepatch
    • --prerelease

    For pre-releases, you can specify the identifier using --versionSuffix <id> (e.g., --preminor --versionSuffix alpha).

  7. Use the changelogen CLI for default changelog generation

    main

    The default command of changelogen generates a changelog by analyzing git commits between two points (or since the last tag) using Conventional Commits. It can automatically bump versions, update files, commit changes, tag releases, and even publish to npm or create GitHub releases.

    Core Workflow

    1. Analyze: It fetches the git diff between from and to points.
    2. Parse: It parses commits based on your configuration.
    3. Bump (Optional): It calculates the next version based on commit types (major, minor, patch, etc.).
    4. Generate: It produces a Markdown changelog.
    5. Output: It either prints the changelog to the console or writes it to a file.
    6. Release (Optional): It can commit the changes, tag the repo, push to origin, and trigger a GitHub release or npm publish.

  8. Execute a full release workflow with changelogen

    main

    When using the --release flag, changelogen automates the Git and publishing lifecycle:

    1. Files: It updates the changelog file and package.json.
    2. Commit: If --commit is not false, it runs git add on the updated files and performs a git commit using the configured commitMessage template.
    3. Tag: If --tag is not false, it creates a git tag using the tagMessage and tagBody templates. It uses -s (signed) if signTags is configured.
    4. Push: If --push is true, it runs git push --follow-tags.
    5. GitHub: If --github is not false and the repository provider is GitHub, it creates a GitHub release with the generated markdown body.
    6. NPM: If --publish is passed, it publishes the package to npm (optionally with a specific --publishTag).

  9. Configure changelogen via ChangelogConfig

    main

    The ChangelogConfig interface defines the available options for generating changelogs. You can provide these options via a configuration file (loaded by c12) or by passing overrides to the loadChangelogConfig function.

    Key configuration areas include:

    • Commit Types: Map commit prefixes (e.g., feat, fix) to titles and SemVer bump types (minor, patch).
    • Scope Mapping: Map commit scopes to human-readable names.
    • Repository: Define the repository source and authentication tokens.
    • Output: Specify the output file path (defaults to CHANGELOG.md if set to true).
    • Publishing: Configure arguments, tags, and privacy for publishing.
    • Templates: Customize commit, tag, and tag body messages using {{newVersion}} placeholders.
    • Authors: Control author visibility via noAuthors, excludeAuthors, or hideAuthorEmail.
    export interface ChangelogConfig {
  cwd: string;
  types: Record<string, { title: string; semver?: SemverBumpType } | boolean>;
  scopeMap: Record<string, string>;
  repo?: RepoConfig | string;
  tokens: Partial<Record<RepoProvider, string>>;
  from: string;
  to: string;
  newVersion?: string;
  signTags?: boolean;
  output: string | boolean;
  publish: {
    args?: string[];
    tag?: string;
    private?: boolean;
  };
  templates: {
    commitMessage?: string;
    tagMessage?: string;
    tagBody?: string;
  };
  noAuthors: boolean;
  excludeAuthors: string[];
  hideAuthorEmail?: boolean;
}

  10. Configure Repository settings via RepoConfig

    main

    When manually providing repository information to changelogen, use the RepoConfig object. This allows you to specify the hosting provider, the repository path, the domain, and an authentication token.

    Supported RepoProvider values are:

    • github
    • gitlab
    • bitbucket

  11. CLI Reference: Arguments and Flags

    main

    The changelogen CLI allows fine-grained control over changelog generation, version bumping, and publishing.

    Core Arguments:

    • --from: Start commit reference (defaults to latest git tag).
    • --to: End commit reference (defaults to latest commit in HEAD).
    • --dir: Path to git repository (defaults to current working directory).
    • --output: Changelog file name (defaults to CHANGELOG.md). Use --no-output to write to console only.
    • --clean: Exit if the working directory is not clean.

    Version Bumping & Releases:

    • --bump: Determine semver change and update package.json.
    • --release: Bumps version, creates git commit and tags.
      • Use --no-commit to disable commit.
      • Use --no-tag to disable tagging.
      • Use --push to automatically push the new tag and release commit.
    • --major, --minor, --patch: Force a specific semver bump type.
    • --premajor, --preminor, --prepatch, --prerelease: Handle pre-release versioning (can accept an ID string).
    • -r <version>: Release as a specific version.

    Publishing & Canary:

    • --publish: Publishes the package to npm (requires auth via .npmrc or env vars).
    • --publishTag: Custom npm tag for publishing (defaults to latest).
    • --canary: Shortcut for --bump --versionSuffix. If an argument is provided, --nameSuffix is also added.
    • --nameSuffix <suffix>: Adds a suffix to the package name (e.g., --nameSuffix canary changes foo to foo-canary).
    • --versionSuffix: Adds a suffix to the version. If set to true or no value, uses date + commit hash.

    Formatting:

    • --noAuthors: Skip the contributors section.
    • --hideAuthorEmail: Do not include author email if a GitHub username cannot be found.
    npx changelogen@latest [...args] [--dir <dir>]

  12. Determine semver bump type from commits

    main
    The determineSemverChange function calculates the appropriate semantic versioning bump type (major, minor, or patch) based on a list of GitCommit objects and your ChangelogConfig. It maps commit types to semver levels using the config.types mapping. If a commit is marked as isBreaking, it triggers a major bump regardless of the mapped type.