/ 
Test-CPAN-Health-0.1.0
/ Test::CPAN::Health::Check::Changelog

NAME

Test::CPAN::Health::Check::Changelog - Check that a changelog file is present and has an entry for the current version

SYNOPSIS

use Test::CPAN::Health::Check::Changelog;

my $check  = Test::CPAN::Health::Check::Changelog->new;
my $result = $check->run($dist);

printf "%s: %s\n", $result->status, $result->summary;

DESCRIPTION

Verifies that the distribution root contains a changelog file (Changes, Changelog, CHANGES, ChangeLog, CHANGELOG, CHANGELOG.md, NEWS, or NEWS.md) and, when the distribution version is determinable from META, that the file contains a release entry for that version.

Score matrix:

  • 100 -- Changelog found with an entry for the current version (or version is unknown).

  • 50 -- Changelog file found with content, but no entry for the current version.

  • 10 -- Changelog file exists but is empty.

  • 0 -- No changelog file found.

LIMITATIONS

  • Version-entry detection is heuristic. It matches the most common CPAN (0.01 YYYY-MM-DD) and Keep a Changelog ([0.01] - YYYY-MM-DD) formats but may miss exotic styles.

  • Only the distribution root directory is searched; changelogs in subdirectories are not recognised.

run

PURPOSE

Locate a changelog file in the distribution root and verify it contains a release entry for the current version.

API SPECIFICATION

INPUT

dist     Test::CPAN::Health::Distribution  required
context  Hashref                           optional

OUTPUT

Test::CPAN::Health::Result with check_id 'changelog'.

MESSAGES

Code  | Severity | Message                                          | Resolution
------+----------+--------------------------------------------------+-----------
CL001 | FAIL     | No changelog file found                          | Create a Changes file
CL002 | FAIL     | Changes exists but is empty                      | Add release notes
CL003 | WARN     | Changes found but no entry for version N.NN      | Add a version entry
CL004 | PASS     | Changes found with entry for version N.NN        |
CL005 | PASS     | Changes found (version not determinable)         |

FORMAL SPECIFICATION

Pre:  dist isa Test::CPAN::Health::Distribution
Post: (no changelog)  => status = fail  /\ score = 0
      (empty file)    => status = fail  /\ score = 10
      (no ver entry)  => status = warn  /\ score = 50
      (ver entry ok)  => status = pass  /\ score = 100

SIDE EFFECTS

Reads at most one file from disk.

USAGE EXAMPLE

my $result = Test::CPAN::Health::Check::Changelog->new->run($dist);
print $result->summary;

AUTHOR

Nigel Horne, <njh at nigelhorne.com>

LICENSE AND COPYRIGHT

Copyright (C) 2026 Nigel Horne.

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.