Auto-update changelogs from commits

Auto-updating changelogs from commits is a powerful way to keep documentation synchronized with code changes, especially in collaborative or CI/CD-driven projects. Here’s how to implement this automation, using conventional commits and changelog generation tools:

1. Use Conventional Commits

Adopt the Conventional Commits specification to ensure consistent formatting of commit messages.

Example format:

pgsql
CopyEdit
feat: add user authentication feature
fix: correct login token bug
docs: update API usage instructions

This format enables tooling to parse commit messages and categorize them into changelogs.

2. Set Up Changelog Generator

Use a tool like standard-version, semantic-release, or auto-changelog.

Option A: standard-version

Install:

bash
CopyEdit
npm install --save-dev standard-version

Add to package.json:

json
CopyEdit
"scripts": {
  "release": "standard-version"
}

Usage:

bash
CopyEdit
npm run release

This creates/updates a CHANGELOG.md, bumps the version, and tags a release based on commits.

Option B: semantic-release

Install:

bash
CopyEdit
npm install -D semantic-release @semantic-release/changelog @semantic-release/git

Configure .releaserc.json:

json
CopyEdit
{
  "branches": ["main"],
  "plugins": [
    "@semantic-release/commit-analyzer",
    "@semantic-release/release-notes-generator",
    ["@semantic-release/changelog", {
      "changelogFile": "CHANGELOG.md"
    }],
    ["@semantic-release/git", {
      "assets": ["CHANGELOG.md", "package.json"]
    }]
  ]
}

CI/CD Integration:
Set up semantic-release to run automatically on merges to your main branch in GitHub Actions, GitLab CI, etc.

3. Automate with Git Hooks or CI Pipelines

For local workflow automation, use Husky:

Install:

bash
CopyEdit
npm install husky --save-dev
npx husky install

Add hook:

bash
CopyEdit
npx husky add .husky/prepare-commit-msg 'npx --no -- commitlint --edit $1'

For CI, configure the changelog generation step before deployment or packaging.

4. Customize the Output

Each changelog tool can be customized to include issue links, scopes, or custom sections:

json
CopyEdit
{
  "types": [
    {"type": "feat", "section": "Features"},
    {"type": "fix", "section": "Bug Fixes"},
    {"type": "docs", "section": "Documentation"},
    {"type": "refactor", "section": "Code Refactoring"},
    {"type": "test", "hidden": true}
  ]
}

5. Example Workflow with GitHub Actions

yaml
CopyEdit
name: Release

on:
  push:
    branches:
      - main

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '20'
      - run: npm install
      - run: npx semantic-release
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

6. Best Practices

• Enforce conventional commits using commitlint.

• Always review changelogs before release.

• Tag versions consistently to match changelog entries.

• Consider adding manual notes for breaking changes.

By automating changelog generation from commits, you ensure consistent documentation, faster releases, and better collaboration between developers and stakeholders.