Beefy Boxes and Bandwidth Generously Provided by pair Networks
P is for Practical

Revision Standards

by Dranzaz (Sexton)
on Jan 22, 2009 at 16:13 UTC ( #738207=perlquestion: print w/replies, xml ) Need Help??
Dranzaz has asked for the wisdom of the Perl Monks concerning the following question:

I am curious if there is a published standard for revision histories? I have not been able to find anything yet this morning and my boss is updating a document from 1.9 and needs to know if 1.10 is acceptable or if it should be 2.0? Help me gain some brownie points.....thanks in advance.

Replies are listed 'Best First'.
Re: Revision Standards
by mikelieman (Pilgrim) on Jan 22, 2009 at 16:19 UTC
    If you don't *have* standards already, this is your opportunity to create them.

    Do you think of them as Version.Release ?
    If so, then 1.10 is fine. It would be better if 1.9 had been 1.09 ( it sorts into a more natural order ) but that boat has sailed. Save the major numbers ( 1. 2. 3. ) for major updates, and just keep bumping the minor number whenever needed.

Re: Revision Standards
by BrowserUk (Pope) on Jan 22, 2009 at 16:25 UTC
      marketing is logic
        Looks like we have a Zen monk visiting the Monastary.

        May I offer you a tea of cup?

        use JAPH;
        print JAPH::asString();

Re: Revision Standards
by atcroft (Abbot) on Jan 22, 2009 at 16:22 UTC

    My understanding of the general practice is that if it is a "major" revision, change the first number, but if it is a "minor" revision, change the second. That being said, in the case you describe, if he is making corrections, changing phrasing, or updating with more current figures, but not changing the general statement of the document, then I would think it a minor revision. If, however, there are important changes in positions or items in the document, then a major revision number change seems reasonable.

    Hope that helps.

Re: Revision Standards
by almut (Canon) on Jan 22, 2009 at 16:33 UTC

    Version numbers are mostly not interpreted as real numbers to a base of ten. In other words, there's no reason that incrementing the 'decimal point part' of 1.9 by 1 would lead to 2.0.

    Think of it this way: if that would be the case, we'd already have Perl 6.0 released as stable — i.e. 5.9 => 6.0 instead of 5.9 => 5.10 ;)

Re: Revision Standards
by ELISHEVA (Prior) on Jan 22, 2009 at 21:58 UTC

    I think the most important thing to keep in mind, whatever conventions you choose, is that various build, configuration tools, and packaging systems all have different conventions about the *format* of version numbers.

    The actual numbering you choose (1.10 vs 2.0) is a matter of taste and marketing. A few years back Sun got worried that people would think Java was immature so it gave Java 1.5 two version numbers: 1.5 and 5.0. Some people like to reserve odd minor numbers (the X in 1.X) for development versions and even numbers for published versions. This lets one keep new development versions ahead of the last published release and before the next published release. The main thing is that you form an in house policy and stick to it.

    One thing to keep in mind is that many automation systems expect that 1.X and 2.0 are binary incompatible - they represent such a large change that code using a 1.X API will need to be rewritten if consumers upgrade to anything 2.X. Also many people (and some automated packaging systems - e.g. Microsoft's MSI) expect that 2.X.1 and 2.X.2 represent bug fixes that add no new features.

    As for specific systems and formats:

    • cvs doesn't allow dots - if you are using cvs for version control (some people still do) and want to tag things with their version number, you will need to translate all your dots to dashs or hyphens.
    • perl - when assigning a value to $VERSION in your perl modules, you should probably reformat version numbers for your $VERSION variable N.NNNNNN, e.g. 1.9.5 becomes 1.009005 - if you don't Perl will think that 1.1 is version 1.100 and 1.10 is version 1.010 - not at all what you want: It messes up anyone who uses a version number in their require statement. Even though 1.10 is a later version Perl will think it is an earlier one an refuse to load it.
    • CPAN If you are uploading distribution files to CPAN, there is a convention that N.NNN_NNN is a development release - available for testing by CPAN testers but not for general consumption.
    Perhaps others will contribute additional examples.

    Internally, we use a perl module that keeps track of which of our tools need which kinds of version number formats and spits out the right format for whatever packaging tool or code file we are creating.

    Best, beth
Re: Revision Standards
by jdporter (Canon) on Jan 22, 2009 at 18:32 UTC

    In my last job as a configuration manager, I, with some trepidation, established a numbering scheme which allows 1.91.10. In the end, it turned out not to be a problem. The one downside — inconvenient ordering when you do a default "asciibetical" sort — was very minor and almost never a problem, in contrast to the upsides, which are not having to allocate an expected maximum width for the numeric fields, not having to remind your users to pad with zeroes, not having to worry about software interpreting the number as base 8, and so on.

    Between the mind which plans and the hands which build, there must be a mediator... and this mediator must be the heart.
Re: Revision Standards
by brian_d_foy (Abbot) on Jan 22, 2009 at 17:59 UTC

    In Perl, version numbers are really just strings. The string 1.10 would sort before 1.9 even though the version 1.10 comes after 1.9. You're kinda stuck, though, since you can't change the past.

    The trick is to put in more decimal places, so version 1.9 is really 1.09 or 1.009, just like Perl 5.10 is really 5.010.

    brian d foy <>
    Subscribe to The Perl Review
Re: Revision Standards
by samtregar (Abbot) on Jan 23, 2009 at 05:13 UTC
    In my opinion if it looks like a number it should act like a number. There's already a well-established way to increment 1.9 without going all the way to 2.0, just increment to 1.95. If anyone is unclear as to where 1.95 falls on the number line you can direct them back to junior high.

    This isn't a completely abstract choice - it's often necessary to do actual math on version numbers. Imagine you've decided you support version 1.3 and higher of a particular browser. In a magical world where version numbers are treated like floats your job is easy - $version >= 1.3. But in our world you have to somehow guess the intent of number - will 1.10 come along someday and expect to be treated higher than 1.9? There's really no way to know! Either way you code it could turn out to be very wrong.


Re: Revision Standards
by targetsmart (Curate) on Jan 23, 2009 at 06:30 UTC
Re: Revision Standards
by DrHyde (Prior) on Jan 23, 2009 at 10:59 UTC

    It depends whether you think of these as version numbers or not. If they are *numbers* then they need to go up, and so you can't go from 1.9 to 1.10, as 1.10 == 1.1 which is less than 1.9. Instead, go from 1.9 to 1.91. Then from 1.99 to 1.991, and so on. Or You could go from 1.9 to 2, then 3, then 4, and so on.

    More importantly, I suppose it depends on whether your users, auditors, or software think of them as number.

Re: Revision Standards
by puudeli (Pilgrim) on Jan 23, 2009 at 08:02 UTC

    At $WORK we use three-digit scheme: Major.Minor.Defect, for example, 2.2.3

    seek $her, $from, $everywhere if exists $true{love};

Log In?

What's my password?
Create A New User
Node Status?
node history
Node Type: perlquestion [id://738207]
Approved by Corion
Front-paged by Arunbear
and all is quiet...

How do I use this? | Other CB clients
Other Users?
Others wandering the Monastery: (2)
As of 2018-05-28 00:24 GMT
Find Nodes?
    Voting Booth?