Stories
Slash Boxes
Comments
NOTE: use Perl; is on undef hiatus. You can read content, but you can't post it. More info will be forthcoming forthcomingly.

All the Perl that's Practical to Extract and Report

use Perl Log In

Log In

[ Create a new account ]

Changes.yml specs v0.01

Journal written by RGiersig (3217) and posted by brian_d_foy on 2007.09.07 7:50   Printer-friendly
CPAN
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
---

«  Quick Security Fix For the Day | Copenhagen, Denmark to host YAPC::Europe 2008  »
Changes.yml specs v0.01 | Log In/Create an Account | Top | 9 comments | Search Discussion
Display Options Threshold:
The Fine Print: The following comments are owned by whoever posted them. We are not responsible for them in any way.

  • What I'd want

    (Score:1)
    by Skud (28) on 2007.09.07 9:52 (#57590)
    ( http://infotrope.net/ | Last Journal: 2007.08.22 15:14 )

    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 account of this" vs "mostly of use to the maintainer" is worth noting.

    A week or so back I came across some kind of XML format for changelogs. I have no recollection as to what it was, just that I hated it for its non-human-readability. You might want to investigate and see what it includes.

    Random things that you might want to be able to capture in your YAML format:

    • change of license
    • change of maintainer
    • flag for "major release!!!!1"
    • packaging changes (is license change a subset of this?)
    • test changes
    • documentation changes
    • bugfixes
    • features added *or* removed
    • changes in maturity, eg "I now consider this to be out of alpha, and ready for use by others" or "this is a release candidate"
    • developer releases?

    And please, make the YAML format be in reverse chronological order. This is much better for human readability because hte most recent changes are most readily apparent.

    --
    Kirrily "Skud" Robert perl@infotrope.net http://infotrope.net/

  • Maybe something more along the TAP philosophy?

    (Score:1)
    by GunnarWolf (8049) on 2007.09.07 12:23 (#57598)
    ( http://gwolf.org/ )
    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 has the advantage to clearly point out which action caused which bug to be closed - it's not the whole version which closes a bug, but a specific action included in it.

  • Maybe we should take a step back...

    (Score:1)
    by RGiersig (3217) <reversethis-{gro.napc} {ta} {gisreiGR}> on 2007.09.08 18:57 (#57638)
    ( Last Journal: 2007.09.07 6:17 )
    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. After the release, the original specification is retroactively changed by reported but previously unknown "features" that we normally call "bugs". During bug-fixing, these "features" are removed and the change is documented in the specification of the next release.

    I don't know what I will make of all this, it's rather late and I'm going to bed now.

    Does this make any sense for you others that are not me? :o)
Stories, comments, journals, and other submissions on use Perl; are Copyright 1998-2006, their respective owners.