Changelog Maintenance

When to use this skill

• Before release: organize changes before shipping a version

• Continuous: update whenever significant changes occur

• Migration guide: document breaking changes

Instructions

Step 1: Keep a Changelog format

CHANGELOG.md:

Changelog

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

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

Unreleased

Added

• New user profile customization options
• Dark mode support

Changed

• Improved performance of search feature

Fixed

• Bug in password reset email

1.2.0 - 2025-01-15

Added

• Two-factor authentication (2FA)
• Export user data feature (GDPR compliance)
• API rate limiting
• Webhook support for order events

Changed

• Updated UI design for dashboard
• Improved email templates
• Database query optimization (40% faster)

Deprecated

• GET /api/v1/users/list (use GET /api/v2/users instead)

Removed

• Legacy authentication method (Basic Auth)

Fixed

• Memory leak in background job processor
• CORS issue with Safari browser
• Timezone bug in date picker

Security

• Updated dependencies (fixes CVE-2024-12345)
• Implemented CSRF protection
• Added helmet.js security headers

1.1.2 - 2025-01-08

Fixed

• Critical bug in payment processing
• Session timeout issue

1.1.0 - 2024-12-20

Added

• User profile pictures
• Email notifications
• Search functionality

Changed

• Redesigned login page
• Improved mobile responsiveness

1.0.0 - 2024-12-01

Initial release

Added

• User registration and authentication
• Basic profile management
• Product catalog
• Shopping cart
• Order management

Step 2: Semantic Versioning

Version number: MAJOR.MINOR.PATCH

Given a version number MAJOR.MINOR.PATCH, increment:

MAJOR (1.0.0 → 2.0.0): Breaking changes

• API changes break existing code
• Example: adding required parameters, changing response structure

MINOR (1.1.0 → 1.2.0): Backward-compatible features

• Add new features
• Existing functionality continues to work
• Example: new API endpoints, optional parameters

PATCH (1.1.1 → 1.1.2): Backward-compatible bug fixes

• Bug fixes
• Security patches
• Example: fixing memory leaks, fixing typos

Examples:

• 1.0.0 → 1.0.1 : bug fix

• 1.0.1 → 1.1.0 : new feature

• 1.1.0 → 2.0.0 : Breaking change

Step 3: Release Notes (user-friendly)

Release Notes v1.2.0

Released: January 15, 2025

🎉 What's New

Two-Factor Authentication

You can now enable 2FA for enhanced security. Go to Settings > Security to set it up.

Export Your Data

We've added the ability to export all your data in JSON format. Perfect for backing up or migrating your account.

✨ Improvements

• Faster Search: Search is now 40% faster thanks to database optimizations
• Better Emails: Redesigned email templates for a cleaner look
• Dashboard Refresh: Updated UI with modern design

🐛 Bug Fixes

• Fixed a bug where password reset emails weren't being sent
• Resolved timezone issues in the date picker
• Fixed memory leak in background jobs

⚠️ Breaking Changes

If you're using our API:

• Removed: Basic Authentication is no longer supported

  • Migration: Use JWT tokens instead (see Auth Guide)

• Deprecated: GET /api/v1/users/list

  • Migration: Use GET /api/v2/users with pagination

🔒 Security

• Updated all dependencies to latest versions
• Added CSRF protection to all forms
• Implemented security headers with helmet.js

📝 Full Changelog

See CHANGELOG.md for complete details.

Upgrade Instructions: docs/upgrade-to-v1.2.md

Step 4: Breaking Changes migration guide

Migration Guide: v1.x to v2.0

Breaking Changes

1. Authentication Method Changed

Before (v1.x): ```javascript fetch('/api/users', { headers: { 'Authorization': 'Basic ' + btoa(username + ':' + password) } }); ```

After (v2.0): ```javascript // 1. Get JWT token const { accessToken } = await fetch('/api/auth/login', { method: 'POST', body: JSON.stringify({ email, password }) }).then(r => r.json());

// 2. Use token fetch('/api/users', { headers: { 'Authorization': 'Bearer ' + accessToken } }); ```

2. User List API Response Format

Before (v1.x): ```json { "users": [...] } ```

After (v2.0): ```json { "data": [...], "pagination": { "page": 1, "limit": 20, "total": 100 } } ```

Migration: ```javascript // v1.x const users = response.users;

// v2.0 const users = response.data; ```

Deprecation Timeline

• v2.0 (Jan 2025): Basic Auth marked as deprecated
• v2.1 (Feb 2025): Warning logs for Basic Auth usage
• v2.2 (Mar 2025): Basic Auth removed

Output format

CHANGELOG.md # Developer-facing detailed log RELEASES.md # User-facing release notes docs/migration/ ├── v1-to-v2.md # Migration guide └── v2-to-v3.md

Constraints

Required rules (MUST)

• Reverse chronological: latest version at the top

• Include dates: ISO 8601 format (YYYY-MM-DD)

• Categorize entries: Added, Changed, Fixed, etc.

Prohibited items (MUST NOT)

• No copying Git logs: write from the user's perspective

• Vague wording: "Bug fixes", "Performance improvements" (be specific)

Best practices

• Keep a Changelog: follow the standard format

• Semantic Versioning: consistent version management

• Breaking Changes: provide a migration guide

References

• Keep a Changelog

• Semantic Versioning

Metadata

Version

• Current version: 1.0.0

• Last updated: 2025-01-01

• Compatible platforms: Claude, ChatGPT, Gemini

Tags

#changelog #release-notes #versioning #semantic-versioning #documentation

Examples

Example 1: Basic usage

Example 2: Advanced usage