Skip to content

Instantly share code, notes, and snippets.

@DervishD

DervishD/CHANGELOG.md

Last active January 5, 2026 15:53
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save DervishD/201c7a51c767c4703f732a2e29a7c3ea to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save DervishD/201c7a51c767c4703f732a2e29a7c3ea to your computer and use it in GitHub Desktop.
Download ZIP
DervishD's changelog specification
Raw
CHANGELOG.md

DervishD changelog specification 2026-01-05

This is a specification for a project's CHANGELOG.md file with a format inspired by Keep a Changelog version 1.1.0, but customized, with different styling and wording.

The key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL in this document are to be interpreted as described in RFC 2119.

The first sentence in the file SHOULD be All notable changes to this project will be documented in this file., and if the project adheres to a versioning specification, it SHOULD be specified after that.

After that, the file MUST contain a sequence of project release entries, ordered from most recent to oldest.

Each entry MUST start with a level-2 heading containing a version tag enclosed in square brackets, followed by the release date in ISO 8601 format (YYYY-MM-DD).

The first entry SHOULD be named Development. The Development entry MUST NOT include a release date and SHOULD describe unreleased, in-progress changes.

Each entry MAY begin with a summary paragraph providing context or explanations that do not fit into change sections, and MUST contain zero or more change sections as defined below.

Each change section MUST use a bold section name followed by an unordered list of changes. Empty sections MUST be omitted.

Change section names SHOULD be chosen exclusively from the following list, MUST NOT be repeated within the same release, and SHOULD appear in the order listed below:

  • Security for fixed vulnerabilities
  • Removed for removed features
  • Deprecated for deprecated features
  • Changed for changed features
  • Added for added features
  • Fixed for minor bug fixes

Individual changes MUST NOT repeat the section name as the leading verb, and MAY include additional verbs where appropriate. They SHOULD be written in imperative present tense and MUST NOT end with a period.

If links are available for the releases, they MUST be included at the end of the file, and they SHOULD point to a diff between the previous release and the linked one. If that is not possible, they SHOULD point to the commit corresponding to the tagged release or to the entire source code as a last resort.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment