Releases 1.1.0

Yesterday\’s post was perhaps a bit off the cuff. There were a lot of people really scared about my script, and I don\’t blame them. A lot of good points were brought up. It\’s not that I didn\’t consider them, it\’s just that they\’re already taken into account with how I do revision control. At least Luis had faith in me :)

Below is an example of how I tend to organize a project (my pre-1.0 releases are a bit different, so I\’m just leaving them out for the moment). There are effectively two kinds of tags, fixed (in black) and mobile (in red).

\"\"

Notice that all the fixed tags are three-number versions. This means that if you request my-library_1.1.1.tar.gz, you\’re going to get that same code point all the time. However, you probably don\’t want to do that …

I hate that the three numbers are commonly referred to as \”major\”, \”minor\”, and \”revision\”. That carries no information what-so-ever. My own names for them are more like \”incompatible\”, \”enhancement\”, and \”invisible\” respectively. Increment the \”incompatible; number whenever you delete external symbols, change a method\’s parameters incompatibly, or some other change that prevents the previous style of use from working. Increment the \”enhancement\” number whenever new external symbols are added, or when compatible signature changes are made (EG, adding keyword args). Increment the \”invisible\” number when you add docs, refactor some methods, or otherwise make changes that don\’t affect the outside world.

This then means that when you declare a dependency on my-library v2.1, you\’re really saying \”using the second version of the interface with at least the first set of enhancements\”. So, version checking should make sure that the \”major\” version matches and the \”minor\” number is ≥ the one listed as a dependency.

Now, back to the chart. You\’ll see the red tags all float to the tip of a branch (yeah, that 2.0 tag is just at the end of a 0-length branch — humor me). So, with that graph, a dependency checker should basically look a the local version, see if it\’s 2.x, then make sure x ≥ 1. If it isn\’t, grab my-library_2.tar.gz. Or, if you\’re a bit more cautious, my-library_2.1.tar.gz. That way you get at least the interface required, with possibly some additional functionality, maybe some optimizations, etc.

Now, when you grab that archive, it should actually contain a directory called my-library_2.1.2. Notice how even though you only requested 2.1 (in the name of the archive), you now have the fixed tag in the package. This means that you can check the PGP signature for that exact version, and make sure it\’s cool.

To summarize: the fixed tags (used to name the directory in the tar) represent a precise point in the code and don\’t change. The mobile tags allow you to request only the parts you need to, and receive the newest compatible versions with all the fixes and enhancements that come along with it.

I hope that clarifies my position a bit. Thanks for all the feedback.

2 Responses to “Releases 1.1.0”

  1. Jack Unrue Says:

    Greg, while I do think this is a cool hack, I suspect you are still not quite understanding the problem (and that’s OK, it may not be as much of a bother to you as it has been for me). You are assuming a certain state of mind, or rather, that some amount of thought has gone into when and why a release tag is created. I’m saying that I know of a couple of projects where the developers flat-out don’t care to spend mental cycles on this issue. They might want to use your system to facilitate distribution, but apply no critical thinking at all to exactly what each tag really represents.

  2. mgr Says:

    This probably sounds nice in theory but in practice errors happen. That means that an apparently “invisible” change might in fact introduce a bug.

    And how would you describe a change that solely boosts the operation in terms of running time. It’s might not change the interface in an incompatible fashion and it might not add any keywords or functions, but you wouldn’t really want to call it “invisible”: This performance boost may make the package usable in the first place.

Leave a Reply