abanoub-ashraf/changelog

Changelog & Release Notes

Transform technical git commits into polished, user-friendly changelogs and automate release note generation following industry standards.

When to Use This Skill

• Creating App Store "What's New" text
• Preparing release notes for a new version
• Writing changelog entries for any platform
• Setting up automated changelog generation
• Implementing Conventional Commits
• Managing semantic versioning
• Generating GitHub/GitLab release notes

Quick Start: App Store Release Notes

1) Collect Changes

Run from your repo root:

scripts/collect_release_changes.sh

Or specify a range:

scripts/collect_release_changes.sh v1.2.3 HEAD

2) Triage for User Impact

• Scan commits and files to identify user-visible changes
• Group changes by theme: New, Improved, Fixed
• Drop internal-only work (build scripts, refactors, CI, dependency bumps)

3) Draft Release Notes

• Write short, benefit-focused bullets
• Use clear verbs and plain language
• Aim for 5-10 bullets unless specified otherwise

4) Output Format

# What's New

- Added account switching from the profile menu
- Improved timeline loading speed on slow connections
- Fixed media attachments not opening in full screen

See references/release-notes-guidelines.md for detailed language and filtering rules.

Weekly/Monthly Changelogs

For regular product updates:

# Updates - Week of March 10, 2024

## ✨ New Features

- **Team Workspaces**: Create separate workspaces for different
  projects. Invite team members and keep everything organized.

- **Keyboard Shortcuts**: Press ? to see all available shortcuts.
  Navigate faster without touching your mouse.

## 🔧 Improvements

- **Faster Sync**: Files now sync 2x faster across devices
- **Better Search**: Search now includes file contents, not just titles

## 🐛 Fixes

- Fixed issue where large images wouldn't upload
- Resolved timezone confusion in scheduled posts
- Corrected notification badge count

Keep a Changelog Format

The standard format for project changelogs:

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/).

## [Unreleased]

### Added
- New feature X

## [1.2.0] - 2024-01-15

### Added
- User profile avatars
- Dark mode support

### Changed
- Improved loading performance by 40%

### Deprecated
- Old authentication API (use v2)

### Removed
- Legacy payment gateway

### Fixed
- Login timeout issue (#123)

### Security
- Updated dependencies for CVE-2024-1234

[Unreleased]: https://github.com/user/repo/compare/v1.2.0...HEAD
[1.2.0]: https://github.com/user/repo/compare/v1.1.0...v1.2.0

Conventional Commits

Standard commit message format that enables automation:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

| Type | Description | Changelog Section | |------|-------------|-------------------| | feat | New feature | Added | | fix | Bug fix | Fixed | | docs | Documentation | (usually excluded) | | style | Formatting | (usually excluded) | | refactor | Code restructure | Changed | | perf | Performance | Changed | | test | Tests | (usually excluded) | | chore | Maintenance | (usually excluded) | | ci | CI changes | (usually excluded) | | build | Build system | (usually excluded) | | revert | Revert commit | Removed |

Commit Examples

# Feature with scope
feat(auth): add OAuth2 support for Google login

# Bug fix with issue reference
fix(checkout): resolve race condition in payment processing

Closes #123

# Breaking change
feat(api)!: change user endpoint response format

BREAKING CHANGE: The user endpoint now returns `userId` instead of `id`.
Migration guide: Update all API consumers to use the new field name.

Semantic Versioning

MAJOR.MINOR.PATCH

MAJOR: Breaking changes (feat! or BREAKING CHANGE)
MINOR: New features (feat)
PATCH: Bug fixes (fix)

Automation Tools

Method 1: standard-version (Node.js)

npm install -D standard-version @commitlint/cli @commitlint/config-conventional husky

// .versionrc.js
module.exports = {
  types: [
    { type: 'feat', section: 'Features' },
    { type: 'fix', section: 'Bug Fixes' },
    { type: 'perf', section: 'Performance Improvements' },
    { type: 'revert', section: 'Reverts' },
    { type: 'docs', section: 'Documentation', hidden: true },
    { type: 'style', section: 'Styles', hidden: true },
    { type: 'chore', section: 'Miscellaneous', hidden: true },
    { type: 'refactor', section: 'Code Refactoring', hidden: true },
    { type: 'test', section: 'Tests', hidden: true },
  ],
};

// package.json scripts
{
  "scripts": {
    "release": "standard-version",
    "release:minor": "standard-version --release-as minor",
    "release:major": "standard-version --release-as major",
    "release:patch": "standard-version --release-as patch"
  }
}

Method 2: semantic-release (Full Automation)

// release.config.js
module.exports = {
  branches: ['main', { name: 'beta', prerelease: true }],
  plugins: [
    '@semantic-release/commit-analyzer',
    '@semantic-release/release-notes-generator',
    ['@semantic-release/changelog', { changelogFile: 'CHANGELOG.md' }],
    '@semantic-release/npm',
    '@semantic-release/github',
    ['@semantic-release/git', {
      assets: ['CHANGELOG.md', 'package.json'],
      message: 'chore(release): ${nextRelease.version} [skip ci]'
    }],
  ],
};

Method 3: git-cliff (Rust, Fast)

# Generate changelog
git cliff -o CHANGELOG.md

# Generate for specific range
git cliff v1.0.0..v2.0.0 -o RELEASE_NOTES.md

# Preview without writing
git cliff --unreleased --dry-run

Method 4: commitizen (Python)

# pyproject.toml
[tool.commitizen]
name = "cz_conventional_commits"
version = "1.0.0"
tag_format = "v$version"
update_changelog_on_bump = true

# Create commit interactively
cz commit

# Bump version and update changelog
cz bump --changelog

GitHub Actions Workflow

# .github/workflows/release.yml
name: Release

on:
  push:
    branches: [main]

permissions:
  contents: write

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: actions/setup-node@v4
        with:
          node-version: '20'

      - run: npm ci

      - name: Configure Git
        run: |
          git config user.name "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"

      - name: Run semantic-release
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: npx semantic-release

Release Notes Templates

GitHub Release

## What's Changed

### 🚀 Features
- Feature description by @author in #123

### 🐛 Bug Fixes
- Fix description by @author in #124

### 📚 Documentation
- Docs update by @author in #125

**Full Changelog**: https://github.com/owner/repo/compare/v1.0.0...v1.1.0

Internal Release

# Release v2.1.0 - January 15, 2024

## Summary
This release introduces dark mode and improves checkout performance by 40%.

## Highlights

### 🌙 Dark Mode
Users can now switch to dark mode from settings.

### ⚡ Performance
- Checkout flow is 40% faster
- Reduced bundle size by 15%

## Breaking Changes
None in this release.

## Known Issues
- Dark mode may flicker on initial load (fix in v2.1.1)

Filtering Rules

Include

• New features
• UI changes
• Behavior changes
• Bug fixes users would notice
• Performance improvements with visible impact

Exclude

• Refactors
• Dependency bumps
• CI changes
• Developer tooling
• Internal logging
• Analytics changes (unless affecting user privacy)

Best Practices

Do's

• Follow Conventional Commits for automation
• Write clear, benefit-focused messages
• Reference issues and PRs
• Use scopes consistently
• Automate releases to reduce errors

Don'ts

• Mix multiple changes in one commit
• Skip commit validation
• Manually edit generated changelogs
• Forget to mark breaking changes
• Include internal jargon in user-facing notes

Resources

• scripts/collect_release_changes.sh - Collect commits since last tag
• references/release-notes-guidelines.md - App Store language guidelines
• Keep a Changelog
• Conventional Commits
• Semantic Versioning