Changelog Writer

Overview

A changelog is a vital tool for documenting significant changes in software over time in a format accessible to humans. Unlike developer-oriented commit messages or GitHub's auto-generated release notes, changelogs focus on feature changes rather than code-level details, making them essential for transparency and user communication.

This skill helps you create and maintain professional CHANGELOG.md files following the Keep a Changelog standard, ensuring your project's evolution is clearly communicated to users, contributors, and stakeholders.

When to Use This Skill

• •Starting a new project that needs version tracking and change documentation
• •Preparing for software releases and need to communicate changes clearly
• •Establishing transparency in software development and release cycles
• •Complementing GitHub releases with human-readable feature summaries
• •Onboarding contributors who need to understand project evolution
• •Meeting documentation requirements for enterprise or open-source projects

Prerequisites

• •Semantic versioning familiarity: Understanding of version numbering (MAJOR.MINOR.PATCH)
• •Markdown knowledge: Basic Markdown formatting for consistent documentation
• •Release process awareness: Understanding of your project's release workflow

Why Changelogs Matter

Q: Why maintain a CHANGELOG.md if GitHub has auto-generated release notes?

A: They are complementary tools serving different audiences:

• •GitHub releases: Commit-oriented, developer-focused, platform-dependent
• •Changelogs: Feature-oriented, user-focused, platform-independent

Changelogs ensure:

• •Future-proof accessibility of change information
• •Broader audience understanding beyond developers
• •Feature-centric communication rather than commit-level details
• •Independence from code hosting platforms

Workflow

Step 1: Team Agreement

Before implementing changelogs, discuss their importance with your team:

• •Value proposition: Explain benefits for transparency and user communication
• •Maintenance responsibility: Assign ownership for changelog updates
• •Integration timing: Decide when to update (during development, at release, etc.)
• •Audience consideration: Define who the changelog serves (users, contributors, stakeholders)

Step 2: Create the Changelog

1. •

   Copy the template:

   bash

   cp assets/CHANGELOG.md CHANGELOG.md
   

2. •

   Customize the header:

   • •Replace project-specific information
   • •Ensure Keep a Changelog and Semantic Versioning references remain
3. •

   Add your first release entry:

   • •Replace [INSERT SEMANTIC VERSION...] with actual version (e.g., [1.0.0] - 2024-01-15)
   • •Fill in the change categories with actual changes

Step 3: Maintain the Changelog

For each release, add a new section above previous releases:

## [1.1.0] - 2024-02-15

### Added
- New dashboard feature for user analytics
- Export functionality for reports

### Changed
- Improved performance of search queries
- Updated user interface design

### Fixed
- Fixed login issue with special characters
- Resolved memory leak in background processing

### Removed
- Deprecated legacy API endpoints

Step 4: Integrate with Documentation

1. •

   Link from README.md:

   markdown

   ## Changelog
   
   See [CHANGELOG.md](CHANGELOG.md) for a detailed history of changes.
   

2. •

   Reference in release communications:

   • •Include changelog excerpts in release announcements
   • •Link to changelog from GitHub releases
   • •Reference in project documentation

Keep a Changelog Best Practices

Standard Categories

Use these categories consistently:

• •Added: New features and functionality
• •Changed: Changes to existing functionality
• •Deprecated: Soon-to-be removed features
• •Removed: Features removed in this version
• •Fixed: Bug fixes
• •Security: Security-related changes

Writing Guidelines

1. •Write for humans: Use clear, non-technical language when possible
2. •Focus on impact: Explain what users will experience, not implementation details
3. •Group related changes: Organize similar changes together
4. •Be specific: Avoid vague descriptions like "various improvements"
5. •Include breaking changes: Clearly mark and explain breaking changes

Version Management

• •Use semantic versioning: MAJOR.MINOR.PATCH format
• •Keep dates consistent: Use YYYY-MM-DD format
• •Latest first: Most recent changes at the top
• •Unreleased section: Track upcoming changes before release

Template Usage

The provided CHANGELOG.md template includes:

• •Header: Standard Keep a Changelog format
• •Version section: Template for release entries
• •Change categories: Added, Changed, Removed sections
• •Placeholders: [INSERT...] markers for easy customization

Customization Steps

1. •Replace placeholders: Fill in all [INSERT...] sections
2. •Add relevant categories: Include Deprecated, Fixed, Security if needed
3. •Update project information: Customize header if project-specific details needed
4. •Establish format consistency: Maintain formatting across all entries

Examples and References

Demo Implementations

• •Terraformly Changelog - Real project example
• •Keep a Changelog Example - Reference implementation

Additional Resources

• •Keep a Changelog - Official standard and examples
• •Semantic Versioning - Version numbering guidelines
• •SLIM Documentation - Comprehensive changelog guide

Common Patterns

Breaking Changes

### Changed
- **BREAKING**: Authentication now requires API keys (see migration guide)
- Updated user permissions model

Security Updates

### Security
- Fixed XSS vulnerability in user input validation
- Updated dependencies to address security advisories

Deprecation Notices

### Deprecated
- Legacy API endpoints (will be removed in v2.0.0)
- Old configuration format (use new YAML format)

Assets Available

• •CHANGELOG.md: Complete Keep a Changelog template with standard sections and placeholders for easy customization

Troubleshooting

Q: How often should I update the changelog? A: Update for every release, or maintain an "Unreleased" section for ongoing changes.

Q: What if I forgot to document changes in previous releases? A: You can retroactively add changelog entries, but mark them clearly as retrospective updates.

Q: Should I include every small change? A: Focus on user-facing changes. Minor bug fixes and internal refactoring may not need detailed changelog entries.

Q: How do I handle breaking changes? A: Mark them clearly with BREAKING labels and provide migration guidance or links to documentation.