NAME
    Test::Changes::Strict::Simple - Strict semantic validation for CPAN
    Changes files

SYNOPSIS
        use Test::More;
        use Test::Changes::Strict::Simple qw(changes_strict_ok);

        changes_strict_ok('Changes');

        done_testing;

    Typically used in "xt/release/" and guarded by:

        plan skip_all => 'Release tests only'
            unless $ENV{RELEASE_TESTING};

DESCRIPTION
    "Test::Changes::Strict::Simple" provides strict semantic validation for
    CPAN-style Changes files.

    While other modules focus primarily on structural validation, this
    module performs additional consistency checks, including:

    *   The indentations must be uniform.

    *   No trailing spaces.

    *   No white characters other than spaces.

    *   No more than three blank lines at the end of the file.

    *   No version without items

    *   First line must be a title matching:

           qr/
              ^
               Revision\ history\ for\ (?:
                 (?:perl\ )?
                 (?:
                   (?:module\ \w+(?:::\w+)*)
                 |
                   (?:distribution\ \w+(?:-\w+)*)
                 )
               )
               $
             /x;

    *   Title lines and version lines are never indented.

    *   A version line consists of a version string and a date separated by
        blanks.

    *   Dates match "/\d+\.\d+/".

    *   Versions are strictly monotonically increasing.

    *   Release dates are valid calendar dates. Only dates, no time.

    *   Release dates are not in the future.

    *   Release dates are not earlier than the first public Perl release
        (1987).

    *   Release dates are monotonically non-decreasing (multiple releases on
        the same day are allowed).

    Note: an item can span more than one line.

    Example of a valid Changes file:

       Revision history for distribution Foo-Bar-Baz

       0.03 2024-03-01
         - Another version, same day.

       0.02 2024-03-01
         - Bugfix.
         - Added a very fancy feature that alllows this
           and that.
         - Another bugfix.

       0.01 2024-02-28
         - Initial release. This will hopefully work
           fine.

    If you do not want periods at the end of the items, set the import
    option "-check_dots" to 0. If you want an empty line after each version
    line, set the import option "-empty_line_after_version" to 1.

    The module is intended for use in release testing and helps detect
    common mistakes such as version regressions, invalid dates, and
    chronological inconsistencies.

EXPORT
    By default, the following symbols are exported:

       changes_strict_ok

IMPORT OPTIONS
  -check_dots => *BOOL*
    By default, items must end with a period. This check can be disabled by
    passing "-check_dots" with a value of *"false"*. Example:

        use Test::Changes::Strict::Simple -check_dots => 0;

  -empty_line_after_version => *BOOL*
    By default, the first element must immediately follow the version line.
    Passing "-empty_line_after_version" with a *"true"* value changes this
    behavior so that there must be exactly one blank line between a version
    line and the first element. Example:

        use Test::Changes::Strict::Simple -empty_line_after_version => 1;

  -no_export => *BOOL*
    If true, no symbols are exported.

       use Test::Changes::Strict::Simple -no_export => 1;

    is equivalent to:

       use Test::Changes::Strict::Simple ();

    This option is useful in conjunction with other import options. Example:

       use Test::Changes::Strict::Simple -empty_line_after_version => 1, -no_export => 1

  -version_re => *REGEXP*
    By default, version numbers must match "qr/\d+\.\d+/". This can be
    overridden by passing a custom compiled regular expression via
    "-version_re". Note that version strings must be valid with respect to
    the "version" module.

FUNCTIONS
  changes_strict_ok(*"NAMED_ARGUMENTS"*)
    Runs strict validation on the given Changes file.

    Named arguments:

    "changes_file"
        Optional. File to be validated. If no file is provided, "Changes" is
        assumed.

    "module_version"
        Optional. If specified, the function checks whether the highest
        version is equal to *"module_version"*. This is done by comparing
        strings.

    The function emits one test event using "Test::Builder" and can output
    diagnostic messages if necessary. It does not plan tests and does not
    call "done_testing".

    Returns *"true"* if all checks pass, *"true"* otherwise.

LIMITATIONS
    The module expects a traditional CPAN-style Changes format:

        1.23 2024-03-01
          - Some change.

    Exotic or highly customized Changes formats may not be supported.

BUGS
    Please report any bugs or feature requests to
    "bug-test-changes-strict-simple at rt.cpan.org", or through the web
    interface at
    <https://rt.cpan.org/NoAuth/ReportBug.html?Queue=Test-Changes-Strict-Sim
    ple>. I will be notified, and then you'll automatically be notified of
    progress on your bug as I make changes.

SUPPORT
    You can find documentation for this module with the perldoc command.

        perldoc Test::Changes::Strict::Simple

    You can also look for information at:

    *   RT: CPAN's request tracker (report bugs here)

        <https://rt.cpan.org/NoAuth/Bugs.html?Dist=Test-Changes-Strict-Simpl
        e>

    *   Search CPAN

        <https://metacpan.org/release/Test-Changes-Strict-Simple>

    *   GitHub Repository

        <https://github.com/klaus-rindfrey/perl-test-changes-strict-simple>

SEE ALSO
    *   Test::CPAN::Changes

        Basic structural validation of CPAN Changes files.

    *   Test::CPAN::Changes::ReallyStrict

        Stricter validation rules for Changes files.

    *   Test::Version

        Checks module version consistency.

    *   CPAN::Changes

        Parser and model for Changes files.

    Furthermore: Test::Builder, Time::Local, version

AUTHOR
    Klaus Rindfrey, "<klausrin at cpan.org.eu>"

LICENSE
    This software is copyright (c) 2026 by Klaus Rindfrey.

    This library is free software; you may redistribute it and/or modify it
    under the same terms as Perl itself.