Module-Changes

hanekomu on 2007-11-08T16:01:11

There has been some discussion about a machine-readable Changes file.

I'm maintaining a few distributions myself and have phases of making some changes to several distributions. Opening the Changes file, copying a few lines, inserting the current date and time and so on gets tedious.

I wanted to have a command-line tool with which to interact with Changes files. Also the Changes file should be machine-readable. So I wrote Module-Changes. I've chosen YAML for the format, although this is by no means mandatory - it's easy to write a new parser or formatter for your format of choice. Integration of new parsers, formatters etc. is something I still have to work on, though.

Some see YAML as a "failed format", but enough people (me included) find it useful and easy to read for both humans and machines, so that's what I've chosen as the default format. Even so, we need to agree on a YAML schema - that is, the layout of the Changes file.

This is not set in stone, it's more of a proposal. I'm hoping for a discussion of what people like or don't like in the current version, and what they would like to see in future versions.

Change YAML syntax?

srezic on 2007-11-08T20:19:59

Unfortunately the YAML syntax you chose cannot be expressed with a http://search.cpan.org/dist/Kwalify schema. These alternatives probably can:

--- global: name: Module-Changes log: - v0.02: author: ... changes: - ... - v0.01: changes: - ... --- global: name: Module-Changes log: v0.02: author: ... changes: - ... v0.01: changes: - ...

The second one is shorter to write, but unfortunately there's no guarantee that the log mapping is sorted. This must be assured by an application, e.g. using version.pm or so.

Re:Change YAML syntax?

Alias on 2007-11-09T02:01:20
I don't find that very readable... lots of chrome...

Format of Changes.yml

RGiersig on 2007-11-09T09:33:45

I have given this already some thoughts here: http://use.perl.org/user/RGiersig/journal/34370/

What I came up with is a stream of yaml docs (separated by '---'), each containing a hash with info about that version. The reason to use a stream of separate docs is to cut back on indentation ("chrome"). So we only have one indentation level for the lists which means we can easily correct the format if somebody forgets to put the two spaces before the '- ' list token.

Below is an example of how a Changes.yml could look like. I have refined some points. "api-stability" is a declaration if the author thinks that the API is powerful enough so it will only be added to, maintaining backward-compatibility on the API level. I hope the rest of the format is self-explanatory.

--- version: 0.02 # plain number or version string, required released-at: 2007-11-09 # datestring, required released-by: Roland Giersig <RGiersig@cpan.org> # release author, required api-stability: draft # stable | draft, required backward-compatibility: partial # full | partial | none, required breaks-compatibility-in: # list of subs, optional - foo() - bar() bugs-fixed: # list of bugs with references, optional - foo() crashes when given undef parameter <http://rt.cpan.org/Ticket/Display.html?id=1234> - bar() should return "blah" major-new-features: # list of text, optional - now also handles the BAZ protocol detailed-changes: # list of text, optional - rearranged arguments to foo() - changed return value of bar() --- version: 0.01 released-at: 2007-09-05 released-by: Roland Giersig <RGiersig@cpan.org> api-stability: draft backward-compatibility: none license-changed-to: Artistic # new license reference, optional maintainer-changed-to: RGIERSIG # CPAN User Id of new maintainer, optional ---

Re:Format of Changes.yml

hanekomu on 2007-11-09T10:06:15

I've seen your proposal and also thought about it.

It seems a bit too detailed. Also I don't think that splitting the structure into different YAML streams for the sake of indentation is ideal. I don't mind indentation - after all, it's supposed to be machine-readable.

If you really want a human-readable version as well, just have the YAML in Changes.yml and run:
changes -f Changes.yml -ff >Changes
By the way, more updates are coming. I've simplified the YAML somewhat (less indentation!) and added a YAML validator that uses a schema with Kwalify.pm. v0.04 should be on CPAN soon.

Re:Format of Changes.yml

Corion on 2007-11-09T13:27:42

...after all, it's supposed to be machine-readable...

Sorry, but if you keep it that way, it won't get much ground. First and foremost, it should be conveniently human-writable, everything else comes afterwards. Because if you can't write it conveniently as a human, people won't use the format and stay with "unreadable" formats for Changes files. Having the Changes file generated from Changes.yml adds complexity to the build process which is somewhat acceptable if it's easily (1 line in Makefile.PL) automated and hidden away.

Personally, I believe that putting too much "machine-only information" into Changes (for example the RDF-abomination) makes it impossible for me as a human to take a glance at the Changes file and see what changed. Putting too much structure into the YAML thing is about the same - I already dislike the --- stream delimiters where a simple newline does the same, but those stream delimiters are very close to the structural limit I'm willing to afford.

But maybe there is a need for a parser that parses the more conventional format(s) of Changes files, so if you can make your module have the appropriate hooks to guess the format of a Changes file and then call the appropriate parser plugin, that would be a convenient start. People who use your module can then support other formats by writing new parsers.

Re:Format of Changes.yml

Corion on 2007-11-09T13:43:46

I'm stupid. I just saw Module::Changes::Parser::Free , which does just what I proposed. Thank you for anticipating my complaints :))