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

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

A simplified parseable format for Changes files 16 Comments More | Login | Reply /

 Full
 Abbreviated
 Hidden
More | Login | Reply
Loading... please wait.
  • in most programming languages prefix ! is a negation so I think using postfix ! is a better choice.

    just my 0.02 EUR
  • Unfortunately, due mainly to lack of indenting I don't like you format.

    Of course, I don't like all the other proposals equally as much.

    • The spec allows you to do this if you want:

      a!
        Added some groovy new feature.
      b
        Fixed that stupid little bug in the gnomon.

      Any better?

  • Each line begins with a token denoting what it describes ... The token is followed by \s+. If an item is split onto multiple lines, it is understood to continue until a new token or block break is reached.

    Maybe I missed something, but what do you do if the word 'a' is the first letter of an item split onto multiple lines? How does the parser know that's not a token?

    • Ooh, good catch. As it stands, it wouldn't. The workaround is not to split a line before an "a" :-)

      If anyone can think of a patch to the spec to fix that without adding complexity (I can't off the top of my head) I'd be interested to hear it.

      • As a format which could conceivably be written in other (human) languages, can you guarantee that none of them will have the same issue? Or that someone might refer to their 'd' subroutine and mess things up?

        Maybe subsequent lines could be indented or the preceding line could end in a backslash?

        • confound on IRC suggested starting continued lines with a '.', but that's more chrome to impede a quick visual scan of the document, as are backslashes. On the other hand, the backslash is a well-known line continuation indicator. I prefer though your suggestion of indenting. Leading whitespace already seems to be commonly used on CPAN to indicate a continued comment.

          a We added a new shiny feature that you'll all love:
            a magic automatic doodad configurator.
          b! A major bug got fixed. Really m

  • Looking at your list of abbreviations, it makes a lot of sense to me, except for one detail: the "d". I believe I'm not the only one to expect the "d" to mean "delete". Instead, "d" is for docs, "r" is for remove. So you've solved it by choosing another word instead of "delete"...

    But I'm sure mistakes are bound to be made. That people accidentally use "d" instead of "r".

    Instead I'd prefer to use another letter for "documentation", but I can't think of any other word.

    • Hmm. "d" for "delete" is a good point, however I find the phrasing "I deleted a feature" a little awkward.

      How about we take a leaf out of diff -u's book and circumvent the issue of which word to use?

      -  removed something
      +  added something

      There's no ambiguity in that...

      • I find the alphabetical codes rather unreadable. They mix too much with the text. Having tags for version number and date seems redundant when those two items are essential (and currently standard anyway.) In my rendition, the version and date are a non-indented header over a set of indented paragraphs which start with sigils.

        v0.1.1 2007-11-10

            + added new thing() method

            - removed old deal() method

            * fixed bug #12578

            % changed code for blah()

         

        • I thought the metaphor for the maintainer symbol was that someone changed their “hat” (as in “putting on my group leader hat, I say that […]”). That seemed funnily apt to me.

  • I think that *incompatible changes* and *security fixes* are very important to indicate separately in a machine readable way. Just like security fixes make you install the new version asap, incompatible changes make you wait until you have tuits for updating your code. (And when they're there together, good luck.)

    For these, I suggest "i" and "s".

    Actually, single letters make bad identifiers. How about the following self-descriptive tags:

    new
    fix
    doc
    incompatible
    license
    maint
    security
    tests

    Where changes and removal
    • I agree with Juerd on all points, but most especially that using a word rather than a letter helps a lot with readability. So, what he said.
      --
      Kirrily "Skud" Robert perl@infotrope.net http://infotrope.net/
    • Compatibility, security, fix: agree that these are necessary splits to "bug fix" ("b" in my original scheme).

      Timestamps: these follow the format specified in ISO 8601 [wikipedia.org], where the "T" is a mandatory separator. I'd like to stick to an existing standard of date representation if possible.

      I think uppercasing is too shouty... adding the important marker would make you end up with "FIX! SECURITY! NEW!". It's a bit tabloid newspaper. :-)

      With all this in mind I'm going to post a revised spec shortly for a seco

      • I think the important marker itself is not important if you split out security/incompatible. If something new is important, bump the version number.

        As for the timestamp, you'd have two things, whitespace separated, instead of one. dateTtime may be the standard, but date time is much more commonly seen in the wild. And for a very good reason.
Stories, comments, journals, and other submissions on use Perl; are Copyright 1998-2006, their respective owners.