GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  CPAN::CHANGES::SPEC (3)

.ds Aq ’

NAME

CPAN::Changes::Spec - Specification for CPAN Changes files

CONTENTS

VERSION

version 0.04

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

This document describes version 0.03 of the specification for Changes files included in a CPAN distribution.

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.

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. <B>Note:B> 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:
o Unknown Release Date
o Unknown
o Not Released
o Development Release
o Development
o 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>



<B>NOTE:B> The characters between a Version and a Date must start with whitespace, but may subsquently 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

o CPAN::Changes
o 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.

Search for    or go to Top of page |  Section 3 |  Main Index


perl v5.20.3 CPAN::CHANGES::SPEC (3) 2014-10-10

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.