use Perl

• Format of Changes.yml (Score:1)

  by RGiersig (3217) <RGiersigNO@SPAMcpan.org> on 2007.11.09 4:33 (#58941) Journal

  I have given this already some thoughts here: http://use.perl.org/~RGiersig/journal/34370/ [perl.org]
  
  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
  ---

  Reply to This

  • Re: (Score:1)

    by hanekomu (8123)

    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
  • Re: (Score:1)

    by Corion (7288)

    ...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) autom
    • Re: (Score:1)

      by Corion (7288)

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