RL003: ChangelogFormatCheck

Overview

Property Value
ID RL003
Name ChangelogFormatCheck
Group release
Severity WARNING

Description

Validates that the changelog follows a consistent, parseable format.

A well-formatted changelog:

  • Is easy for users and tools to parse
  • Follows established conventions
  • Enables automated release notes generation
  • Improves project professionalism

What it checks

The check validates changelog files against common formats:

Keep a Changelog format

## [1.2.0] - 2024-03-15

### Added
- New feature X

### Changed
- Updated behavior Y

### Fixed
- Bug fix Z

Validated elements

  • Version headers: Properly formatted ## [X.Y.Z] or ## X.Y.Z
  • Date format: ISO 8601 dates (YYYY-MM-DD)
  • Category headers: Standard categories (Added, Changed, Fixed, etc.)
  • Unreleased section: Presence of ## [Unreleased] for upcoming changes
  • Link references: Version comparison links at file bottom

Result states

  • PASSED: Changelog follows valid format
  • FAILED: Format issues detected (with specific errors)
  • SKIPPED: No changelog file found

How to fix

Use Keep a Changelog format

# Changelog

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

The format is based on [Keep a Changelog](https://keepachangelog.com/),
and this project adheres to [Semantic Versioning](https://semver.org/).

## [Unreleased]

### Added
- New feature description

## [1.0.0] - 2024-01-15

### Added
- Initial release with core functionality

### Fixed
- Bug fix description

[Unreleased]: https://github.com/user/repo/compare/v1.0.0...HEAD
[1.0.0]: https://github.com/user/repo/releases/tag/v1.0.0

Standard categories

Use these categories in order:

Category Use for
Added New features
Changed Changes to existing functionality
Deprecated Features to be removed in future
Removed Features removed in this release
Fixed Bug fixes
Security Security-related fixes

Common format issues

# Bad: Missing date
## [1.0.0]

# Good: Include ISO date
## [1.0.0] - 2024-01-15

# Bad: Wrong date format
## [1.0.0] - January 15, 2024

# Good: ISO 8601 format
## [1.0.0] - 2024-01-15

# Bad: Inconsistent version format
## v1.0.0
## 1.1.0

# Good: Consistent format
## [1.0.0] - 2024-01-15
## [1.1.0] - 2024-02-20

Tooling support

Use tools to maintain changelog format:

# Validate changelog format
npx changelog-parser CHANGELOG.md

# Auto-generate from git commits (with conventional commits)
npx conventional-changelog -p angular -i CHANGELOG.md -s

Why WARNING severity?

This check is a WARNING because:

  • Changelog content is more important than strict format
  • Projects may use alternative valid formats
  • Legacy projects may have mixed formats

However, consistent formatting improves usability.

Configuration

Skip this check

[tool.pycmdcheck]
skip = ["RL003"]

CLI

pycmdcheck --skip RL003