Beefy Boxes and Bandwidth Generously Provided by pair Networks
Do you know where your variables are?
 
PerlMonks  

Versions Thought

by pileofrogs (Priest)
on Mar 13, 2006 at 21:33 UTC ( [id://536391]=perlmeditation: print w/replies, xml ) Need Help??

The most common version number for a brand new module is 0.0.1. This might not mean what you want it to mean to some people. The problem is, a major number of '0' sometimes means 'pre-release' and sometimes just means '1st major version' with no value attached to the alpha/beta/release quality.

So, unless you're intentionally denoting that your module is 'pre-release', it might be best to start off at 1.0.0.

Here's an example: You're in the 1st major release, 5th minor release and 13th patch release. It's not pre-release. It's production quality.

1.5.13 seems to really say exactly that.

0.5.13 might be saying exactly that, or it might be saying all that PLUS this module is not considered release quality.

If your module is NOT release ready, I have no problem with a major release number of 0. I also have no problem with a major release number of 1 or 23 or whatever. You are not limited to the version number as the location of your statement about the release status of your module.

I only think it's unclear to label a release quality module with a major version number of 0.

This runs right into another topic: When do you consider your module production quality? I'm not going to take a stab at that right now. I just wanted to urge folks who have production quality modules to use a major version number greater than 0.

--Pileofrogs

Update: Yet again I have demonstrated what a lousy writer I am.

I am saying it would be best if people started at 0 and jumped to 1 when they're ready to release. However, since a lot of folks don't do that, they should just start at 1.

Replies are listed 'Best First'.
Re: Versions Thought
by BrowserUk (Patriarch) on Mar 13, 2006 at 22:51 UTC

    As I described in Re: Versioning modules in a package, in the system I've used most in the past, the major part of a 3 part version number identifies the external interface release.

    To my way of thinking, a 0.x.x version number indicates that the module is a proof of concept. Most likely a first attempt prototype with an interface defined on-the-fly, that is highly likely to change once a better picture of the scope and difficulty of the task has been assessed, and some usability of the interface has been tested.

    It says:

    • This module is not yet released and may never be released.
    • It is unlikely to have ever been fully tested.
    • It is very likely to contain bugs.
    • Some of those bugs may already be known about and have not yet been and quite likely will never be addressed.
    • It should only be used for conceptual assessment of the goals and interface design.

      Comments, critiques and suggestions regarding the goals and interface are sought and welcomed.

      Do not test the implementation as it is intended only for the sake of exploration on the concept.

      Do not waste time developing patches as it is quite likely that the code you are patching will never see light of day in it's current form.

    • It should under no circumstances be used for anything that is required to work.

    If you believe that the interface is likely stable, and that the implementation is reasonable, whilst not guarenteeing that all possible use cases have been thought of, covered and tested--then release it.

    The first Release should be 1.0.0.

    So yes, I am in agreement in as far as, if you intend that what you have is usable by yourself first and others second, then it should be 1.0.0, but you should only start with 1.0.0 if you are working to a predefined interface and only providing a new implementation of it.

    If you are inventing a new interface for something, start with 0.0.1 and once you have convinced yourself that you have a reasonable interface design that is likely to remain stable for a while and only be extended rather than completely redesigned in the forseable future, then release it as 1.0.0.


    Examine what is said, not who speaks -- Silence betokens consent -- Love the truth but pardon error.
    Lingua non convalesco, consenesco et abolesco. -- Rule 1 has a caveat! -- Who broke the cabal?
    "Science is about questioning the status quo. Questioning authority".
    In the absence of evidence, opinion is indistinguishable from prejudice.
Re: Versions Thought
by dragonchild (Archbishop) on Mar 13, 2006 at 21:39 UTC
    I always start with '0.01' and go up from there. Then, generally, I have a major API/featureset upgrade. That's when I roll over the numbers to 1.00, then go up from there.

    Only once have I ever released a module at 1.00 and that was Class::Lazyload. I did it that way because the featureset was so limited and the testcases mostly obvious, so stvn and I could inspect and figure we'd covered almost everything.


    My criteria for good software:
    1. Does it work?
    2. Can someone else come in, make a change, and be reasonably certain no bugs were introduced?

      I think you might be exactly my target audience for this meditation.

      Your version system is an example of one that contains no data about the pre-release or production ready status of your modules. Anyone who assumes version numbers encode that information could be mislead by your system.

      Instead of starting at 0 and moving to 1 when you make your first big API/featureset changes, you could start at 1, and lose absolutely NO data, but gain some clarity (or more to the point, remove ambiguity). Or, said from the reverse direction, when you hit major version 1, you may have been giving the false impression that you were declairing your module production-ready.

      Probably the best idea would be to start at 0, and then magically jump to 1 when you feel like your module is production ready, even when there aren't any major API/featureset changes. Then increment the major version number for every major API/featureset change after that.

Re: Versions Thought
by PodMaster (Abbot) on Mar 13, 2006 at 23:35 UTC
    This might not mean what you want it to mean to some people.
    Its true, a lot of people read too much into a version number. Some people resort to using dates ( yearmonthdatey ).

    If you want to label your module as alpha/beta/release, do so unambiguously, in the documentation.

    MJD says "you can't just make shit up and expect the computer to know what you mean, retardo!"
    I run a Win32 PPM repository for perl 5.6.x and 5.8.x -- I take requests (README).
    ** The third rule of perl club is a statement of fact: pod is sexy.

Re: Versions Thought
by xdg (Monsignor) on Mar 13, 2006 at 22:18 UTC

    I think there's two sets of thinking on this: Those who think "0" means pre-release, and those (ahem, programmers) who just starting counting from "0".

    Personally, I tend to use major "0" to indicate still-under-development -- a few I promote to "1" when I feel that the API is unlikely to change further and I feel the module is well tested.

    -xdg

    Code written by xdg and posted on PerlMonks is public domain. It is provided as is with no warranties, express or implied, of any kind. Posted code may not have been tested. Use of posted code is at your own risk.

Re: Versions Thought
by spiritway (Vicar) on Mar 14, 2006 at 02:17 UTC

    When I need to identify something as alpha, I place that actual string into the version number. Ugly, but gets the point across without ambiguity.

    Nothing I've written has gone beyond that point yet. I'll worry about what to do when the problem arises.

Re: Versions Thought
by revdiablo (Prior) on Mar 14, 2006 at 02:41 UTC
    So, unless you're intentionally denoting that your module is 'pre-release', it might be best to start off at 1.0.0.

    It's an interesting thought. On one hand, I can see how it might avoid a lot of needless hand wringing. Plenty of effort is spent thinking and talking about when 1.0 is going to be released. I can understand the argument that this should be headed off at the pass by just starting at 1.0 from the beginning. On the other hand, I'm not sure how much value people really put into a simple version number. There are so many different schemes that have such different amounts of value attached to them, I cannot imagine any but the most naive user attributing very much importance to them.

    Sure, people talk about it a lot, but do experienced admins or programmers really make decisions about what to used based on a number? I think (hope?) they go more on their peers' opinions, and the gut feeling they get when doing basic research on the project. Granted, examining the version numbers may be a small portion of that research. But I know I certainly spend more time browsing the documentation, looking for functionality, signs of maturity, and basic traces of sanity.

      Yeah, I think I was imagining Dilbert's pointy-haired boss making a declaration that no modules with version numbers below 1 shall be used.

        there are many 0.x modules in the perl core itself...
Re: Versions Thought
by salva (Canon) on Mar 13, 2006 at 22:23 UTC
    The most common version number for a brand new module is 0.0.1.

    Most new modules are not release quality but just alpha or beta quality. Releasing a new module with a 1.xx version number is a bad idea, even if it has been extensively tested in-house, because it can have problems with its API that would remain undiscovered until somebody starts using it for something the developer never though.

    In my opinion it is a better idea to use a 0.xx version number that says, try it, tell me what you think, and then I would try to correct the problems to finally release something stable.

      Releasing a new module with a 1.xx version number is a bad idea, even if it has been extensively tested in-house, because it can have problems with its API that would remain undiscovered until somebody starts using it for something the developer never though.

      If the module has been "extensively tested in-house", then the interface as-is is worthy of release.

      But that partly reflects my missive that nothing is tested until it has been used. That is, no amount of potted test suites, unit tests or other non-use testing are a substitute for using the code for real. And no interface or code can be described as having been extensively tested, until a real(istic) application has been written using it, and (in most cases), by a developer who is not a part of the development team.

      Of course this gets fuzzy with one-man, and even one-team development shops, but the basic principle holds. Don't develop librabries or interfaces in the absence of a real use-case and a real application that meets that use-case.

      By that measure, if the interface/library have been used successfully for a use-case, and it meets the requirements of that use-case, then it is worthy for release. Others may have a sufficiently similar use-case that it will meet their requirements.

      They may also discover requirements and ommisions that would allow the module to be (more easily or more completely), adapted to their use-case and if they do, and if those requirements do not impact the original use, then extensions to the interface may be in order. They may also feed back that for their use-case the current interface is inadaquate.

      The original developers may see benefits, to their current application, or future applications, or just the general usability and effectiveness of the module, and choose to adapt it and release a new interface; but the original use-case may continue to be perfectly sufficient as-is, and not require adaption to the new interface until that happy state changes.

      Even after the new interface is released, the original interface may be sufficient and complete for some new applications, and should continue to be mainatained and supported until it is evident that it uneconomic (an ethereal judgement with free software) to do so. One real benefit that falls out of f/oss software is that if the original developers choose to drop support for an older release, it is possible for users for whom that old release is all they need, to avoid the costs of upgrading and take on the maintainence themselves.

      What it comes down to (IMO), is that code should be developed to meet a (real) requirement, not a hypothetical one. And it should not be released until it has proven useful in meeting that real requirement. Only at that point is the interface "proven", and therefore likely to be useful to others.

      Code written to meet a set of theoretical goals and requirements, no matter how well coded, tested and documented, has yet to pass the fundemental goal of solving a real problem.

      Every project I've ever been involved with (at any level), that was written to a designer's view of what might be needed, rather than a "customers" needs, has expended huge amounts of time and money solving the wrong problems and invariably missed the boat when it comes to solving the real problems.

      And every library I've ever used that was written to meets the possible, maybe, nice-to-have, future requirements of some theoretical problem has invariably been a pig of an interface to work with when you try to use it solve real problems, now.

      Indeed, I've arrived at a credo that says solve the real problems now, and deal with future problems as and when they arise. A programmer should of course avoid coding arbitrary limits tailored to meet just the current requirements--don't use a fixed-sized static array because it's easier to code than a dynamically allocated one. That will always come back to bite you :).

      But neither should he speculate too much about what might be needed at some unspecified point in the future, and over complicate the code to accomodate that possibility. By the time that eventuality arises, there will invariably be 20 other good reasons for refactoring the code, and the chances are a better solution will fall out of that reengineering to solve that, now current need, than you could have achieved at the time when you thought it might be a good idea.


      Examine what is said, not who speaks -- Silence betokens consent -- Love the truth but pardon error.
      Lingua non convalesco, consenesco et abolesco. -- Rule 1 has a caveat! -- Who broke the cabal?
      "Science is about questioning the status quo. Questioning authority".
      In the absence of evidence, opinion is indistinguishable from prejudice.

Log In?
Username:
Password:

What's my password?
Create A New User
Domain Nodelet?
Node Status?
node history
Node Type: perlmeditation [id://536391]
Approved by friedo
help
Chatterbox?
and the web crawler heard nothing...

How do I use this?Last hourOther CB clients
Other Users?
Others browsing the Monastery: (3)
As of 2024-03-19 05:17 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    No recent polls found