​
Changelog Management Guide

This guide explains how to maintain the CHANGELOG.md and GitHub releases for VibeTunnel.

​
Overview

We maintain a comprehensive changelog that:
  • Documents all user-facing changes
  • Credits contributors properly with GitHub links
  • Tracks first-time contributors for each release
  • Provides clear, user-friendly descriptions

​
Using the /changelog Command

The /changelog command in Claude Code analyzes git history to generate comprehensive changelogs: 
# In Claude Code, simply type:
/changelog
This command:
  • Analyzes commit history beyond just titles
  • Examines actual file changes to understand user impact
  • Groups changes by category (Features, Bug Fixes, Performance, etc.)
  • Writes user-focused descriptions (not developer jargon)

​
Changelog Format

​
Version Header

## [1.0.0-beta.13] - 2024-12-20

​
Categories

  • Features - New functionality
  • Improvements - Enhancements to existing features
  • Bug Fixes - Fixed issues
  • Performance - Speed/efficiency improvements
  • Developer Experience - Build, test, or development improvements

​
Attribution Format

Every change should credit its contributor: 
- Added systemd service management for Linux deployments (via [@hewigovens](https://github.com/hewigovens)) (#419)
Format: - Description (via [@username](https://github.com/username)) (#PR)

​
First-time Contributors Section

For releases with new contributors: 
### First-time Contributors
- [@hewigovens](https://github.com/hewigovens) - Added systemd service management for Linux (#419)

​
Identifying Contributors

​
Finding First-time Contributors

# Get all contributors up to a specific release
git log --format="%an|%ae" v1.0.0-beta.12 | sort -u

# Get contributors for a specific release
git log --format="%an|%ae" v1.0.0-beta.12..v1.0.0-beta.13 | sort -u

# Compare to find first-timers

​
Mapping Changes to Contributors

# Find who made specific changes
git log --oneline --author="username" v1.0.0-beta.12..v1.0.0-beta.13

# Get detailed commit info with files
git log --stat --author="username" v1.0.0-beta.12..v1.0.0-beta.13

​
Special Cases

​
Bot Contributors

Do not highlight bot contributors as first-time contributors or include them in the contributors list:
  • devin-ai-integration[bot]
  • blacksmith-sh[bot]
  • Other *[bot] accounts
Important: Bot contributions should be completely excluded from:
  • First-time contributors sections
  • The main contributors list at the end of CHANGELOG.md
  • GitHub release notes contributors sections
Bot changes can be mentioned in regular changelog entries (e.g., “Added SwiftLint hooks”) but without attribution.

​
Core Team

Core team members (repository owners) don’t need “(via @username)” attribution unless specifically requested.

​
Multiple Contributors

If multiple people worked on a feature: 
- Feature description (via [@user1](https://github.com/user1), [@user2](https://github.com/user2)) (#123)

​
GitHub Releases

​
Creating a Release

  1. Generate changelog using /changelog command
  2. Review and edit the generated content
  3. Update CHANGELOG.md with the new version section
  4. Create GitHub release: 
    gh release create v1.0.0-beta.14 \
  --title "v1.0.0-beta.14" \
  --notes-file release-notes.md \
  --prerelease

​
Release Notes Format

The GitHub release should include:
  1. Highlights - 2-3 major changes
  2. Full changelog - Copy from CHANGELOG.md
  3. First-time contributors - If applicable
  4. Installation instructions - Brief reminder
Example: 
## Highlights
- 🐧 Linux systemd service support for production deployments
- 🔧 Improved authentication reliability
- 🚀 Better performance for large terminal outputs

## What's Changed
[Copy from CHANGELOG.md]

## First-time Contributors
- @hewigovens made their first contribution in #419

## Installation
See [installation instructions](https://github.com/vibetunnel/vibetunnel#installation)

​
Updating Existing Releases

To add first-time contributors to existing releases: 
# Edit a release
gh release edit v1.0.0-beta.13 --notes-file updated-notes.md

# Or use the GitHub web UI

​
Workflow Summary

  1. Before release: Run /changelog to analyze changes
  2. Review output: Ensure proper attribution and user-friendly descriptions
  3. Update CHANGELOG.md: Add new version section with proper formatting
  4. Create release notes: Include highlights and first-time contributors
  5. Create GitHub release: Use gh release create or web UI
  6. Verify: Check that all contributors are properly credited

​
Tips

  • Always verify contributor GitHub usernames for correct links
  • Use clear, non-technical language in descriptions
  • Include PR numbers for traceability
  • Group related changes together
  • Highlight breaking changes prominently
  • Credit everyone who contributed, no matter how small

​
Example Workflow

# 1. Generate changelog
/changelog

# 2. Create release notes file
cat > release-notes.md << 'EOF'
## Highlights
- 🎯 Major feature one
- 🐛 Critical bug fix
- ⚡ Performance improvement

## What's Changed
[Paste from CHANGELOG.md]

## First-time Contributors
- @newcontributor made their first contribution in #123

## Installation
See [installation instructions](https://github.com/vibetunnel/vibetunnel#installation)
EOF

# 3. Create release
gh release create v1.0.0-beta.14 \
  --title "v1.0.0-beta.14" \
  --notes-file release-notes.md \
  --prerelease

# 4. Clean up
rm release-notes.md