Discussion so far has mainly been around the use of of YAML. Points raised:
Thinking about all of these, I propose the following. Design constraints were (a) granularity (including Skud's suggestions of what to mention), (b) an absolute minimum of chrome, and (c) trivial to transform into other formats (such as RDF).
# This version was codenamed Muffin because we were listening to Frank Zappa at the time.
m! This project is now maintained by ZIRCON (of Zircon Software fame).
l! We have switched licenses. This software now uses the Greater Zork Software License.
Please ensure that you have read the new license before using this software.
a! New frobnitz() method - save 50 lines of manual frobnitzing by using this instead!
b! Fixed the error in quack() where it would actually moo instead of quack. [RT 1234]
c! The calling convention for rumpelstiltskin() has CHANGED. See perldoc.
t! Test coverage is now 100%! Go us!
# Developer preview for 1.3 and the CPAN testers.
d Fixed some POD formatting mistakes.
c Refactored accessors into AUTOLOAD. Makes no external difference.
r Removed the deprecated honkhonkhonk() method as warned several versions ago.
As you can see, each version is represented by a block of lines. Double line breaks separate versions. Each line begins with a token denoting what it describes, optionally suffixed with an exclamation mark, which means "important". When applied to a version number, it implies "major release". (Applying it to a date or comment is meaningless and should be ignored by any parser.) The token is followed by \s+. If an item is split onto multiple lines, it is understood to continue until a new token or block break is reached.
These are the tokens:
@ Release date. In W3C datetime format (ISO 8601).
# A comment.
a An addition to the code.
b A bugfix. Linking to a ticket here would be nice if it exists.
c A change to existing code.
d A change to documentation.
l A change to licensing.
m A change to the maintainer.
r A removal of something from the code.
t A change to tests.
v A version number.
I haven't gone quite as far as RGiersig did in his specification, as I felt that was a bit heavy. For example, release stability in my scheme is indicated by the version number - that should be implied from the existing convention of underscored version numbers for developer releases.
Vague other thoughts - case-insensitive tokens? And maybe a standard block of comments at the beginning of the file explaining what the tokens are to new readers.
Thoughts? I actually like this enough that I might start using it myself.
Update: There's a second draft now.