use Perl

Changes.yml specs v0.01

Journal written by RGiersig (3217) and posted by brian_d_foy on 2007.09.07 6:50   

OK, I'll bite. Here is a first rough draft for discussion and brain-storming, please post suggestions for add'l hash keys. Basic format of Changes.yml should be a stream of hashes, each hash defining one release.

---
version: 0.02 # plain number or version string, required
released: 2007-09-06 # datestring, required
author: Roland Giersig <RGiersig@cpan.org> # release author, required
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"
changes: # list of text, required
  - rearranged arguments to foo()
  - changed return value of bar()
---
version: 0.01
released: 2007-09-05
author: Roland Giersig <RGiersig@cpan.org> # release author, required
stability: draft
backward-compatibility: none
changes:
  - first release
---

• What I'd want (Score:1)

  by Skud (28)

  I've been doing CPAN Watch [perlbuzz.com] for a couple of weeks now and I'm starting to get a handle on what I'd want if I had a machine-parsable changelog. A few random notes:

  To me, the main distinction in changelogs is "noteworthy" and "not noteworthy". Bugfixes, additional features, and breaking backwards compatibility are noteworthy. Things like packaging fixes, test improvements, etc are not noteworthy. Admittedly my criteria are very personal here, but I think the distinction of "you might want to upgrade on

  --
  Kirrily "Skud" Robert perl@infotrope.net http://infotrope.net/
  • Re: (Score:1)

    by RGiersig (3217)

    Hmm, cpan watch would really be a major user of this, so I'll keep that in mind. So I guess making too many things in Changes.yml optional is bad, either an author should include all infos or just leave out Changes.yml alltogether.
    
    So the release info should contain human-readable info on the one hand like a one-sentence synopsis for cpan-watch and parseable info on the other hand like API-changes, changes in dependencies etc that allows some nifty tools to combine that with info from other packages to e.g.
    • Re: (Score:1)

      by sjn (3626)

      META.yml is rather established, and quite useful for determining the current state of a package. I don't think it's productive to speculating in merging files or making one replace the other.

      Instead, I suggest that Changes.yml ONLY contains information regarding the changes between releases (as opposed to info regarding about the release itself, which is available in META.yml). That would mean fields like "author" should be redundant/meaningless in Changes.yml.

      Furthermore, there's much to be won by maki
      • Re: (Score:1)

        by RGiersig (3217)

        Right, I don't intend to merge files, and be it just for backward-compatibility.
        
        With "author" I meant the author of that specific release, not necessarily of the whole module. I don't know if "pumpking" would be better, as I see that title as a honor to those that coordinate releases on really large module/packages/whatever. Maybe "brought-to-you-by" would be better... No, let that be "release-author". :-)
        
        [Which brings me to the point if there shouldn't be a list of bug/patch contributors that could be auto
• Maybe something more along the TAP philosophy? (Score:1)

  by GunnarWolf (8049)

  I really like the TAP in that whatever its parser does not understand is taken as a comment (and ignored, of course). I'd suggest you to take a look at how Debian handles its changelogs: They have a clearly defined format to allow programs to harvest its most important bits of information (i.e. version, timestamp, maintainer, priority...). Each changelog entry line is then basically text, but can specify some action (i.e. having a «(Closes #nnnnnn)» at the end causes that bug to be closed. This ha
  • Re: (Score:1)

    by GunnarWolf (8049)

    Just to illustrate my point, the changelog for mod_perl2 in our SVN repository [debian.org].
• Maybe we should take a step back... (Score:1)

  by RGiersig (3217)

  Thniking about everything I come to a wider viewpoint: the Changelog is actually a diff between two module feature descriptions. So how about doing exactly that: lets create a formalized feature description for each version. This description needs only be quite basic, because we only want the diffs. So the first release is described by its documentation and following releases are adding and changing its features.
  
  Come to think of, the process is in two steps:
  
  With each release, a new specification is created.
  • Re: (Score:1)

    by sjn (3626)

    Interesting idea, but perhaps it's better not to over-engineer this early? :)

    I think it would be better to define a minimal spec that's easy to implement, and possible to extend when it's useful to do that. And of course, it should be human-readable/scannable firstly (as that's the role of the Changes files today). Using valid YAML ought to fix the "machine-parsable" requirement nicely.

    YAML.pm seems to have tried to do something in that direction too, btw. Maybe worth taking a look/having a chat with so
    • Re: (Score:1)

      by RGiersig (3217)

      Well, I see adaption of such a thing mainly as a psychological problem, not a technical one. So I want to get the technique right, and this means to decide what semantics we want here. But you are right, lets keep it small and simple. :-)
      
      Yes, the YAML changelog is valid YAML. Apart from that, they started out to put each change as one stream entry, thus generating multiple entries with the same version instead of having one entry per version and the changes as a list. Well, that's a mistake that I wont make