ai-chang

An AI-powered tool for automatically generating technical changelogs based on git changes between releases.

Installation

Global Installation

npm install -g ai-chang

Local Project Installation

# npm
npm install --save-dev ai-chang

# yarn
yarn add -D ai-chang

Usage

As an npm script

1. Add the script to your package.json:

{
  "scripts": {
    "changelog": "ai-chang --from",
    "changelog:detailed": "ai-chang --from $npm_config_from --detailed",
    "changelog:save": "ai-chang --from $npm_config_from --output CHANGELOG.md",
    "changelog:update": "ai-chang --from $npm_config_from --update-main"
  }
}

2. Run with parameters:

# Basic usage (concise format, from tag to current commit)
npm run changelog --from=v1.0.0

# With specific end tag
npm run changelog --from=v1.0.0 --to=v1.1.0

# Detailed changelog
npm run changelog:detailed --from=v1.0.0

# Save to file
npm run changelog:save --from=v1.0.0

# Update main changelog file (AI_CHANGELOG.md)
npm run changelog:update --from=v1.0.0

As a CLI command

# If installed globally (from tag to current commit)
ai-chang --from v1.0.0

# With specific end tag
ai-chang --from v1.0.0 --to v1.1.0

# Using npx
npx ai-chang --from v1.0.0

# Save to file
ai-chang --from v1.0.0 --output CHANGELOG.md

# Update main changelog file
ai-chang --from v1.0.0 --update-main

# Update custom main changelog file
ai-chang --from v1.0.0 --update-main --main-changelog custom-changelog.md

Parameters

• --from, -f: Starting tag or commit (required)
• --to, -t: Ending tag or commit (optional, defaults to current commit)
• --output, -o: Output file path (optional)
• --detailed, -d: Generate detailed changelog with technical information (optional)
• --api-key, -k: OpenAI API key (can also be set via OPENAI_API_KEY environment variable)
• --update-main: Update main changelog file (optional)
• --main-changelog: Path to main changelog file (defaults to AI_CHANGELOG.md)

OpenAI API Key Setup

There are several ways to provide the API key (in order of priority):

1. Via command line parameter:

ai-chang --from v1.0.0 --to v1.1.0 --api-key your-api-key

2. Via environment variable in CI/CD (e.g., GitHub Actions):

env:
  OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}

3. Via local .env file:

# .env
OPENAI_API_KEY=your-api-key

Usage Examples

Generating changelog between latest tags

# Get previous tag
PREV_TAG=$(git describe --tags --abbrev=0 HEAD^)
CURRENT_TAG=$(git describe --tags --abbrev=0)

# Generate changelog
npm run changelog --from=$PREV_TAG --to=$CURRENT_TAG

Using with GitHub Actions

name: Generate Changelog
on:
  push:
    tags:
      - 'v*'

jobs:
  changelog:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          fetch-depth: 0 # Important to fetch complete git history

      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'

      - name: Generate Changelog
        env:
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
        run: |
          # Get previous tag
          PREV_TAG=$(git describe --tags --abbrev=0 HEAD^)
          npx ai-chang --from $PREV_TAG --to ${{ github.ref_name }} --output CHANGELOG.md

Requirements

• Node.js >= 18.0.0
• Git installed in the system
• OpenAI API key

Maintaining a Permanent Changelog

ai-chang can maintain a permanent changelog file (similar to release-please) that gets updated with each release:

1. Use the --update-main flag to update the main changelog file:

   ai-chang --from v1.0.0 --update-main

2. By default, it creates/updates AI_CHANGELOG.md in your project root. You can specify a custom file:

   ai-chang --from v1.0.0 --update-main --main-changelog CHANGELOG.md

3. The main changelog file is formatted as follows:

   # AI-Generated Changelog
   
   All notable changes to this project will be documented in this file.
   
   ## [1.0.2] - 2024-03-14
   
   [Latest changes...]
   
   ## [1.0.1] - 2024-03-13
   
   [Previous changes...]

4. When integrated with GitHub Actions, it will:

   • Generate a new changelog entry for the current version
   • Update the main changelog file
   • Include both files in the release PR
   • Use the current version's changes for the GitHub Release