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

[

Unreleased

]

:

https://github.com/username/repo/compare/v1.2.0...HEAD

[

1.2.0

]

:

https://github.com/username/repo/compare/v1.1.2...v1.2.0

[

1.1.2

]

:

https://github.com/username/repo/compare/v1.1.0...v1.1.2

[

1.1.0

]

:

https://github.com/username/repo/compare/v1.0.0...v1.1.0

[

1.0.0

]

:

https://github.com/username/repo/releases/tag/v1.0.0

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 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 } }); ```

1. 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