0.03
A long-lived project that still receives updates
A danger.systems plugin that is OCD about your CHANGELOG.
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
 Dependencies

Runtime

 Project Readme

Danger-Changelog

A plugin for danger.systems that obsessive-compulsively lints your project’s CHANGELOG.md. It can make sure, for example, that changes are attributed properly, have a valid version number, a date in the ISO8601 format, balanced parenthesis and brackets, and that they’re always terminated with a period.

Gem Version Build Status

Table of Contents

  • What’s a correctly formatted CHANGELOG file?
  • Installation
  • Usage
  • Configuration
    • changelog.filename
    • changelog.format
    • changelog.placeholder_line
    • changelog.ignore_files
    • changelog.strict_semver
    • changelog.unreleased_labels
    • changelog.unreleased_heading
    • changelog.only_added
    • changelog.check_intent and changelog.intent_words
    • Conditional reminders
  • Checks
    • changelog.check!
      • changelog.have_you_updated_changelog?
      • changelog.is_changelog_format_correct?
  • Contributing
  • Copyright

What's a correctly formatted CHANGELOG file?

By design, danger-changelog is quite strict with what it allows as a valid changelog file, using the Intridea style, used by this library itself. It also supports the Keep a Changelog format.

Intridea PR and author links can be inline links or Markdown references, with definitions elsewhere in the file. Undefined references are reported without changing the original entry shown in the report.

Entries can begin with multiple inline issue or pull request links separated by , or : , followed by : and the description.

Installation

Requires Ruby 3.1 or newer. Add danger-changelog to your Gemfile.

gem 'danger-changelog'

Call changelog.check! from your Dangerfile. Make a pull request and see this plugin in action.

Usage

Methods and attributes from this plugin are available in your Dangerfile under the changelog namespace.

Configuration

Every option can be set globally on changelog or passed as a keyword to a check. Per-check keywords override global defaults only for that call; parsing and reports use an immutable snapshot. Unknown options and invalid values raise ArgumentError.

changelog.ignore_files = ['README.md', /\.txt$/]
changelog.check!
changelog.check!(filename: 'packages/api/CHANGELOG.md')
changelog.check!(filename: 'CHANGES.md', format: :keep_a_changelog)

Global strings and arrays are copied and frozen; assign a new value rather than modifying a setting in place. The deprecated Danger::Changelog.configure block still sets global defaults.

changelog.filename

Set the CHANGELOG file name, defaults to CHANGELOG.md.

changelog.filename = 'CHANGES.md'
changelog.check!(filename: 'CHANGES.md')

changelog.format

Set the format of the CHANGELOG file.

changelog.format = :keep_a_changelog
changelog.check!(format: :keep_a_changelog)

Available formats are Intridea (default) and Keep a Changelog. Symbol and string format names are accepted.

changelog.placeholder_line

Customize the * Your contribution here. line. Set the value to nil to stop checking for one.

changelog.placeholder_line = "* Your change here.\n"
changelog.check!(placeholder_line: 'Your change here.')

The leading * and trailing newline are added when omitted. This option applies to the Intridea parser; Keep a Changelog does not require a placeholder.

changelog.ignore_files

Ignore additions and changes with a certain name or expression, default is to ignore README.md changes.

For example, ignore UPGRADING.md and all .txt files.

changelog.ignore_files = ['README.md', 'UPGRADING.md', /\.txt$/]
changelog.check!(ignore_files: ['README.md', 'UPGRADING.md', /\.txt$/])

changelog.strict_semver

Require three-component Semantic Versions by default. Set strict_semver: false to accept numeric versions with two or more components, such as 2.0 or 1.2.3.4, with optional prerelease/build suffixes. Date, delimiter, and other formatting checks remain active. This applies to both supported formats.

changelog.strict_semver = false
changelog.check!(filename: 'CHANGES.md', strict_semver: false)

changelog.unreleased_labels

By default (nil), header validation accepts existing label spellings such as Next, next, Unreleased, and project-specific words. Supply a list to replace that permissive behavior with exact, case-sensitive matching in both formats:

changelog.unreleased_labels = ['Next']
changelog.check! # Accepts 0.4.0 (Next), rejects 0.4.0 (next).
changelog.is_changelog_format_correct?(unreleased_labels: ['Next', 'Unreleased'])
changelog.check!(unreleased_labels: nil) # Restore permissive validation for this call.

The list restricts labels following a version (with or without delimiters) and standalone labels enclosed in parentheses, brackets, or braces, such as [Unreleased]. Bare versions, release dates, and ordinary unwrapped titles such as Changelog and Changed: remain unaffected. Labels are literal strings, not regular expressions; custom labels may contain spaces and punctuation. Each must be nonempty, have no leading/trailing whitespace, and contain no newlines or enclosing delimiter characters. An empty list rejects all labels while still allowing dated and bare versions.

This option validates header spelling, not entry placement. Configure unreleased_heading separately if you adopt a custom heading convention; setting the label list does not change its pattern.

changelog.unreleased_heading

By default, added list entries must belong to an unreleased section. The default heading pattern, /(?:\(Next\)|\[Unreleased\])/i, recognizes Intridea's (Next) and Keep a Changelog's [Unreleased], case-insensitively. This global or per-check setting applies to both formats and is enforced by check! after its existing checks pass:

changelog.unreleased_heading = /\(Next\)/
changelog.check!
changelog.check!(format: :keep_a_changelog, unreleased_heading: /\[Unreleased\]/i)
changelog.check!(unreleased_heading: nil) # Allow intentional historical corrections.

Only added * or - list lines in Danger's changelog diff are checked. Nested category headings stay inside the release; the next heading at the same or shallower level ends it. Unchanged historical entries are ignored. Historical corrections appear as additions too; use unreleased_heading: nil for those PRs and release-preparation changes. Customize the pattern for your project's heading convention.

Call changelog.entries_in_unreleased_section?(unreleased_heading: /\(Next\)/) to run this check separately. Missing diff data produces an explicit error rather than silently skipping the enabled check.

changelog.only_added

Format validation and enabled intent validation check the entire file by default (only_added: false). Set only_added: true globally or per check to report line-level format problems and compare intent words only on added lines in Danger's diff. Edited historical entries count as additions. Headers, punctuation, capitalization, attribution, and reference diagnostics follow this scope; reference definitions elsewhere in the file remain available for resolution.

changelog.only_added = true
changelog.check!
changelog.is_changelog_format_correct?(only_added: false)

Missing files, required placeholders, and Keep a Changelog preamble requirements always apply to the whole file. Missing diff data is an explicit failure when added-only checking is requested for a changed changelog. An unchanged file has no added-line diagnostics but still receives global checks.

Release-section placement always checks additions only, regardless of only_added; checking released history against an unreleased section would incorrectly reject existing releases. Use unreleased_heading: nil to disable placement validation.

changelog.check_intent and changelog.intent_words

Opt into a finite dictionary of intent words and consistent wording within each verb family with check_intent: true. This rule is disabled by default and works with both formats. Once enabled, it checks the entire file by default, skipping the configured placeholder and fenced code examples. Set only_added: true to compare only added entries, excluding unchanged history. Missing diff data is an error only when added-only checking is requested for a changed changelog.

changelog.check_intent = true
changelog.check!
changelog.check!(check_intent: true, intent_words: %w[Add Fix Remove])
changelog.intent_correct?(check_intent: true)

The default verb families are Add, Allow, Change, Clarify, Deprecate, Disable, Document, Enable, Fix, Improve, Optimize, Refactor, Remove, Rename, Replace, Revert, Simplify, Support, Update, Upgrade, including their past, third-person present, and gerund forms (for example, Add, Added, Adds, Adding; Fix, Fixed, Fixes, Fixing). Any form is acceptable on its own, but mixing forms within a family fails: Add with Added fails, while repeated Added entries pass. Each family is independent, so Added with Fix passes. Diagnostics ask later entries to match the first form used among the checked entries and include its line number. Unknown words show the allowed dictionary.

intent_words replaces the entire dictionary and must be a nonempty array of single words. Custom words are accepted exactly as listed, without automatic inflection; known forms still belong to their built-in verb family for consistency checks. Matching is case-sensitive, supports Unicode letters, and checks the first word after an optional PR reference or inline link. Setting a dictionary alone does not enable the rule. Projects with non-English prose, emoji-first entries, or inline-code-first descriptions should leave it disabled or adopt a compatible custom word list. Existing format validation remains independent; a custom dictionary does not relax capitalization rules.

Conditional reminders

By default, only README.md is ignored. To skip reminders when all added or modified files are documentation at the repository root, use an anchored pattern. Subdirectory files still require a changelog update.

changelog.ignore_files = [/\A[^\/]+\.md\z/]
changelog.check!

For code-only reminders, use Danger's changed files directly. Keep format validation unconditional, so an edited changelog is checked even when no code changes:

changed_files = git.modified_files + git.added_files + git.deleted_files
changelog.have_you_updated_changelog? if changed_files.any? { |file| file.start_with?('lib/') }
changelog.is_changelog_format_correct?

Other policies can use the same separate checks, such as reminding only for changes larger than 50 lines unless the pull request is marked trivial:

declared_trivial = github.pr_labels.include?('trivial')
changelog.have_you_updated_changelog? if git.lines_of_code > 50 && !declared_trivial
changelog.is_changelog_format_correct?

The label example uses the GitHub plugin; adapt the condition to your provider. Do not also call check! in these conditional examples, because it would run the reminder unconditionally.

Checks

All checks accept the same configuration keywords: filename, format, placeholder_line, ignore_files, strict_semver, unreleased_labels, unreleased_heading, only_added, check_intent, and intent_words. Each uses only the relevant settings.

changelog.check!

Run all checks with defaults, including have_you_updated_changelog?, is_changelog_format_correct?, and entries_in_unreleased_section?. When enabled, intent validation runs after those checks pass.

changelog.check!(filename: 'CHANGES.md', placeholder_line: nil)

As before, format validation runs only if the update reminder passes. The deprecated check also accepts keyword overrides and its legacy positional format, without modifying global defaults.

changelog.have_you_updated_changelog?

Checks whether you have updated CHANGELOG.md.

changelog.have_you_updated_changelog?(filename: 'CHANGES.md', ignore_files: [/\.md$/])

changelog.is_changelog_format_correct?

Checks whether the CHANGELOG format is correct.

changelog.is_changelog_format_correct?(filename: 'CHANGES.md', format: :keep_a_changelog)

The change predicates changelog_changes? and file_changes? accept the same keywords, for example changelog.changelog_changes?(filename: 'CHANGES.md').

Contributing

See CONTRIBUTING.

Copyright

Copyright (c) Daniel Doubrovkine, 2016-2019

MIT License, see LICENSE for details.