AI Changelog

Generate customer-friendly changelogs from git commits using AI. This tool analyzes the differences between two git commits and uses AI to create a well-structured, developer and customer-friendly markdown changelog.

Features

• 🔍 Analyzes git diffs between any two commit hashes
• 📅 Supports date-based ranges (past X days or between two dates)
• 🔎 Automatically finds commits based on dates
• 🤖 Uses AI to generate clear, structured changelogs
• 📝 Proper markdown formatting with appropriate heading levels
• 👥 Customer and developer-friendly language
• 🎯 Groups changes logically (Features, Bug Fixes, Improvements, etc.)
• 📦 Works as both CLI tool and npm package

Installation

npm install aichangelogs

Or install globally:

npm install -g aichangelogs

Usage

CLI

The CLI supports three modes for specifying the commit range:

Mode 1: By Commit Hashes

aichangelogs -f <from-commit> -t <to-commit> -k <openai-api-key> [-o output.md] [-m model] [-r repo-path]

Example:

aichangelogs -f abc1234 -t def5678 -k sk-... -o RELEASE_NOTES.md

Per-Day Mode: Generate separate changelogs for each day between two commits:

aichangelogs -f abc1234 -t def5678 --per-day -k sk-... -o DAILY_CHANGELOG.md

This will generate a changelog for each day between the two commits (inclusive) and append them all to the output file. For example, if commit abc1234 is from Nov 8 and def5678 is from Nov 12, it will generate 5 changelogs (Nov 8, 9, 10, 11, 12) and append them all to the output file.

Mode 2: Past X Days

aichangelogs -d <days> -k <openai-api-key> [-o output.md] [-m model] [-r repo-path]

Example:

# Generate changelog for the past 7 days
aichangelogs -d 7 -k sk-... -o WEEKLY_CHANGELOG.md

Mode 3: Date Range (Inclusive)

aichangelogs --from-date <date> --to-date <date> -k <openai-api-key> [-o output.md] [-m model] [-r repo-path]

Example:

# Generate changelog between two dates
aichangelogs --from-date 2024-01-01 --to-date 2024-01-31 -k sk-... -o JANUARY_CHANGELOG.md

Options:

• -f, --from <commit> - Starting commit hash (Mode 1)
• -t, --to <commit> - Ending commit hash (Mode 1)
• --per-day - Generate separate changelog for each day between commits (Mode 1, requires -f and -t)
• -d, --days <number> - Generate changelog for the past X days (Mode 2)
• --from-date <date> - Start date in YYYY-MM-DD or ISO format (Mode 3)
• --to-date <date> - End date in YYYY-MM-DD or ISO format (Mode 3)
• -k, --api-key <key> - OpenAI API key (or set OPENAI_API_KEY env var)
• -o, --output <file> - Output file path (default: CHANGELOG.md)
• -m, --model <model> - OpenAI model to use (default: gpt-4-turbo-preview)
• -r, --repo <path> - Path to git repository (default: current directory)

Note: You must use one of the three modes. The tool will automatically find the appropriate commits based on your selection.

With environment variable:

export OPENAI_API_KEY=sk-...
aichangelogs -d 7  # Past 7 days
# or
aichangelogs --from-date 2024-01-01 --to-date 2024-01-31  # Date range
# or
aichangelogs -f abc1234 -t def5678  # Commit hashes

Programmatic API

Using Commit Hashes

import { createChangelog } from 'aichangelogs'

const result = await createChangelog({
  fromCommit: 'abc1234',
  toCommit: 'def5678',
  apiKey: process.env.OPENAI_API_KEY!,
  model: 'gpt-4-turbo-preview', // optional
  repositoryPath: './my-repo', // optional, defaults to current directory
})

console.log(result.markdown) // The generated changelog
console.log(result.summary) // Summary message

Using Date-Based Functions

import { createChangelog, getCommitsForPastDays, getCommitsBetweenDates } from 'aichangelogs'

// Option 1: Past X days
const range = await getCommitsForPastDays(7, './my-repo')
const result = await createChangelog({
  fromCommit: range.fromCommit,
  toCommit: range.toCommit,
  apiKey: process.env.OPENAI_API_KEY!,
})

// Option 2: Date range
const startDate = new Date('2024-01-01')
const endDate = new Date('2024-01-31')
const dateRange = await getCommitsBetweenDates(startDate, endDate, './my-repo')
const result2 = await createChangelog({
  fromCommit: dateRange.fromCommit,
  toCommit: dateRange.toCommit,
  apiKey: process.env.OPENAI_API_KEY!,
})

Generating Per-Day Changelogs

import { createChangelogsPerDay } from 'aichangelogs'

// Generate separate changelog for each day between two commits
const result = await createChangelogsPerDay({
  fromCommit: 'abc1234',
  toCommit: 'def5678',
  apiKey: process.env.OPENAI_API_KEY!,
})

// result.markdown contains all daily changelogs appended together
// Each day is separated by a header: ## YYYY-MM-DD

Requirements

• Node.js 18 or higher
• Git repository
• OpenAI API key (Get one here)

How It Works

1. Git Analysis: The tool extracts the git diff between two commits, including:

   • File changes and statistics
   • Commit messages
   • Code differences

2. AI Processing: The diff is sent to OpenAI's API with a carefully crafted prompt that ensures:

   • Proper markdown structure
   • Logical grouping of changes
   • Customer-friendly language
   • Appropriate heading levels

3. Output: A well-formatted markdown file is generated with sections like:

   • Summary
   • Features
   • Improvements
   • Bug Fixes
   • etc.

License

MIT