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.

!2FA Setup

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](docs/auth.md))

• 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](CHANGELOG.md) for complete details.

---

Upgrade Instructions: [docs/upgrade-to-v1.2.md](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