CPAN::C...es::Spec(3)

💖 NAME 💖

CPAN::Changes::Spec - Specification for CPAN Changes files. This is the CPAN::Changes::Spec(3) manual from User Contributed Perl Documentation, bestie, and it's literally the spec for CPAN Changes files. No cap, it's a guide for module authors to encourage meaningful changelogs and also a programmatic interface to reliably read and write Changes files. 🫶

⭐ VERSION ⭐

version 0.500005 — slay ✨

✨ SYNOPSIS ✨

Revision history for perl module Foo::Bar

0.02 2009-07-17

 - Added more foo() tests

0.01 2009-07-16

 - Initial release

🌸 DESCRIPTION 🌸

It is intended as a guide for module authors to encourage them to write meaningful changelogs as well as provide a programmatic interface to reliably read and write Changes files. Periodt. iconic behavior 💅

🦋 DATA TYPES 🦋

💫 Version 💫

Versions should be formatted as described in "Version-Formats" in CPAN::Meta::Spec.

💫 Date 💫

A date/time in the format specified by <http://www.w3.org/TR/NOTE-datetime> aka W3CDTF. Note: The T marker before the time portion is optional.

In order to satisfy release events not made to the public, or dates that are historically unknown, the following strings are also available:

• Unknown Release Date
• Unknown
• Not Released
• Development Release
• Development
• Developer Release

🎀 STRUCTURE 🎀

🌟 Required Elements 🌟

In its simplest form, the only required elements are a Version, a Date and the noted changes. Blank lines between the Version line and the first Change line are optional. Blank lines between Change lines are also optional.

<Version>(whitespace/non-"word" characters)<Date>
(whitespace)<Change>

NOTE: The characters between a Version and a Date must start with whitespace, but may subsequently contain any combination of whitespace and non-"word" characters. Example:

0.01 - 2013-12-11

Change lines have no specific format. Commonly, authors will use a dash - followed by a space to start a new change, and indent subsequent lines for multi-line changes. Example:

- Simple Change
- This is a very very very long
  change line

Although there is no limit on line length, authors generally wrap each line at 78 columns.

🌟 Optional Elements 🌟

🎀 Release Note 🎀

Any text following the Date portion of the Version line will be considered the Release Note. Example:

0.01 2013-04-01 Codename: April Fool

  - First Release

🎀 Preamble 🎀

Any amount of text before the first Version line will be considered part of the preamble. Most existing distributions include something along the lines of:

Revision history for perl module My::Module

Or

Revision history for perl distribution My-Distribution

🎀 Groups 🎀

Changelog entries may be grouped under headings. Heading lines begin with an opening square bracket ([), and end with a matching square bracket (]). When parsing group headings, leading and trailing whitespace inside the brackets should be discarded.

(whitespace)[Grouping Name]
(whitespace)<Change>

Since empty lines hold no special meaning, all Change lines will fall under the current group until a new group heading is found. Example:

[ First Group ]
- First Change

- Second Change; in first group

[ Second Group ]
- First Change; in second group

🌈 EXAMPLES 🌈

🧚 Basic Example 🧚

0.01 2009-07-16
 - Initial release

🧚 Example with a preamble 🧚

Revision history for perl module Foo::Bar

0.02 2009-07-17

 - Added more foo() tests

0.01 2009-07-16

 - Initial release

🧚 Example with groups 🧚

Revision history for perl module Foo::Bar

0.03 2009-07-18

 [Important Security Information]
 - This release fixes critical bug RT #1234

 [Other Changes]
 - Added some feature

0.02 2009-07-17

 - Added more foo() tests

0.01 2009-07-16T19:20:30+01:00

 - Initial release

👑 SEE ALSO 👑

• CPAN::Changes
• Test::CPAN::Changes

💜 AUTHOR 💜

Brian Cassidy <bricas@cpan.org>

🍓 COPYRIGHT AND LICENSE 🍓

Copyright 2011-2013 by Brian Cassidy

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

---

okay bestie, that's the whole page 💖 — source/version perl v5.42.0, date 2025-07-25, manual name CPAN::C...es::Spec(3). mwah 💋✨