Stories
Slash Boxes
Comments

All the Perl that's Practical to Extract and Report

use Perl Log In

Log In

[ Create a new account ]

Changes.yml spec?

Journal written by LTjake (4001) and posted by brian_d_foy on 2007.09.05 23:07   Printer-friendly
User Journal

I was browsing through the solr-ruby project svn directory when i can across CHANGES.yml (sample below):

- v0.0.5
release_date: 2007-08-??
changes:
- Added support for highlighter fragment size to Solr::Request::Standard
- Added support for MoreLikeThese to Solr::Request::Standard
- Added Solr::Request::ModifyDocument (requires SOLR-139 patch)
- Added Solr::Util.query_parser_escape()

- v0.0.4
release_date: 2007-08-16
changes:
- Solr::Indexer#solr added to gain access to the Solr::Connection instance
- Fixed issue with multi-line String field values when field set multiValued="false"
- Fixed tests to work without either Hpricot or libxml2

This makes total sense -- Machine parsable high-level changelogs. I'd love to see a spec created for this. A quick poll of #perl-qa show that some other folks agree. I searched around but couldn't find any existing specs -- any takers? :)

The Fine Print: The following comments are owned by whoever posted them. We are not responsible for them in any way.

Changes.yml spec? 15 Comments More | Login | Reply /

 Full
 Abbreviated
 Hidden
More | Login | Reply
Loading... please wait.
  • It looks like the developers on the project don't use that as machine-parseable file, because it contains errors that prevents the content to be parsed as YAML. Namely, all lines starting as

    - v0.0.4:

    should be ended with ':'. But I think this idea only flies for real simple Changelogs. In CPAN, you find a great diversity of different markup people use for distinct things: bug fixes, new feature implementation, doc patches, etc., etc. That's not easy to be captured in a simple format. And if it is not simp

    • It would be nice to have A optional standard to use though, even if it isn't enforced or even expected.

      I've been meaning to write a Changes file parser/modifier for a while, so I can do automated incremental module releases for some modules.

      This would make it damned easy.
  • Please don't make it YAML, it's a failed format.
    • What are the alternatives?
      • XML. Which raises cries and lamentations of its own, of course. See my longer reply, below.
        --

        --rjray

    • I like YAML but I do wish that it was more widely available. I'm afraid that making it so flexible has made it too difficult to write compliant parsers. One of the things I like about the basic YAML syntax is its simplicity; is it really useful that you can write YAML that looks like Javascript [hobix.com]?
    • Why is it a failed format? Could you provide a reference for that statment?

  • This is a very good idea, but mostly because a standardised changelog format gives us options like automatic pre-release checks of the file ("Have I updated the Changes.yml file before uploading the package to CPAN?") or making new Kwalitee tests for CPAN-friendly packages. :)

    Oh, and the syntax can be "fixed" by adding a ":" after the version number (see v0.0.1 in the example).

    - v0.0.1:
      release_date: 2007-02-15
      changes:
        - initial release

    • Hmf. Should have properly read the other comments [perl.org] first. :-P

      Anyhow, I think that format doesn't look too bad, and I definitely think it may be worth promoting. :)

    • Oh, and the syntax can be "fixed" by adding a ":" after the version number (see v0.0.1 in the example).

      No, fix it right:

      - version: v0.0.1
        release_date: 2007-02-15
        changes:
          - initial release

      And Viola! We have v0.01 of our spec! :-)
      I like YAML for its readability due to its lack of sigils (unlike JSON). And for simple YAML there is YAML::Tiny which can handle those basic structures, namely a list of hashes., just fine...

  • I've been using a home-brewed XML format for some of my changelogs. I also (of course) keep a more traditional-format CL in the distro. I've been working on some XSLT stylesheets and an article about it for XML.com, but lack of tuits has slowed me. This may be the nudge I need to finish it.

    Of course, mentioning XML alone may raise cries from those who are tired of seeing it applied to every vaguely-text-data-related problem that comes along. And I understand (and sometimes share) the sentiment. But in this

    --

    --rjray

    • If you don't need a Schema, you don't need XML...
    • miyagawa has drawn [perl.org] my attention to Net::Flickr::Backup, whose author uses the estimable DOAP [usefulinc.com] RDF vocabulary in his Changes files [cpan.org]. Aaron appears to have extended it in his own fashion, which with a little work could be a very promising format for this sort of thing.

      I'd be very interested to see that overview/article, and perhaps contribute to the effort.

  • I have done a short write-up of a draft for Changes.yml in a personal journal entry at http://use.perl.org/~RGiersig/journal/34370/ [perl.org].

    It's just a quick draft of things that could be handy from my point-of-view as a module maintainer, please add your ideas and positive critiques...
Stories, comments, journals, and other submissions on use Perl; are Copyright 1998-2006, their respective owners.