How to write a changelog on GitHub?

 

Step 1: Understand the Purpose of a Changelog

 

A changelog is a human-readable record of all notable changes made to a project. It helps users and contributors see what’s new, what’s fixed, and what’s been removed or deprecated in each version.

• Define clear versioning (e.g., semantic versioning: MAJOR.MINOR.PATCH).
• Group changes by category (Added, Changed, Deprecated, Removed, Fixed, Security).
• Follow a consistent format so readers can quickly scan for updates.

 

Step 2: Choose a Changelog Format

 

One widely adopted standard is “Keep a Changelog”. It recommends:

• Top‐level file named CHANGELOG.md.
• Headings for each version with release dates.
• Subheadings for categories like Added, Changed, Fixed.

 

Step 3: Create the CHANGELOG.md File in Your Repository

 

At the root of your project, create a new file named CHANGELOG.md:

# Navigate to your repository
cd path/to/your/repo

# Create the changelog file
touch CHANGELOG.md

# Open it in your editor (example using VS Code)
code CHANGELOG.md

 

Step 4: Add the Header and Initial Unreleased Section

 

Start with a header and an “Unreleased” section placeholder. This makes it easy to add upcoming changes before each release.

# Changelog

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

## [Unreleased]

### Added
- 

### Changed
- 

### Deprecated
- 

### Removed
- 

### Fixed
- 

### Security
- 

 

Step 5: Document Changes Under Appropriate Categories

 

For each change you make, update the “Unreleased” section. Use clear, concise descriptions and group each change:

• Added: for new features
• Changed: for modifications in existing functionality
• Deprecated: for soon-to-be removed features
• Removed: for deprecated features removed in this release
• Fixed: for any bug fixes
• Security: in case of vulnerability fixes

## [Unreleased]

### Added
- User login via OAuth2 (#45)
- Export data as CSV option

### Fixed
- Crash on profile update (issue #12)
- Typo in dashboard title

 

Step 6: Version and Release Your Changes

 

When you’re ready to publish a new version:

• Replace the [Unreleased] heading with the new version and date.
• Add a fresh [Unreleased] section below it for the next cycle.

## [1.2.0] - 2024-07-15

### Added
- User login via OAuth2 (#45)
- Export data as CSV option

### Fixed
- Crash on profile update (issue #12)
- Typo in dashboard title

## [Unreleased]

### Added
- 

 

Step 7: Commit, Push, and Publish on GitHub

 

Stage and commit your CHANGELOG.md, then push to GitHub so everyone sees your new release notes.

# Stage the changelog
git add CHANGELOG.md

# Commit with a descriptive message
git commit -m "docs: update changelog for v1.2.0"

# Push to the default branch
git push origin main

 

Step 8: Tag the Release on GitHub

 

Create a Git tag matching your version and push it. This helps GitHub link to your changelog entry in the Releases page.

# Create a version tag
git tag v1.2.0

# Push tags
git push origin --tags

 

Step 9: Maintain and Automate Going Forward

 

To keep your changelog healthy:

• Update CHANGELOG.md as part of every pull request.
• Enforce guidelines via code review templates.
• Consider tools like keep-a-changelog or GitHub Changelog Generator for automation.

 

By following these steps, you’ll have a clear, organized changelog in your GitHub repository that’s easy for others to read and for you to maintain.