Releases
Derek Mahar
I noticed that though you changed the version number in "build.xml" a
few times, you have have not created any new tags or releases. Do you
recall which revision refers to 1.4.0, for example? Will you create a
new tag that points to this revision so that we may build a release
from this tag?
Derek
Nat Pryce
API so the version number needs to be bumped. Before I make a 2.0.0
release I'll create a tag and build the release from that.
--Nat
2008/10/2 Derek Mahar <derek...@gmail.com>:
Derek Mahar
warrants a new tag. How else could we checkout this version again?
Derek
--
Derek Mahar
1.514.560.4949 Mobile
1.514.670.3631 Home
1.514.228.8800 x4150 Work
http://www.derekmahar.ca
102-1365 René-Lévesque Blvd. East
Montreal QC H2L 2M1
Canada
Nat Pryce
> By changing the version number you effectively made a release that
> warrants a new tag. How else could we checkout this version again?
>
> Derek
In that case the release and versioning process is broken.
Anything in trunk is not a release by definition. Checking in to
trunk should *not* be the same as an official release. People make
mistakes. That's why we use version control -- to let us back out
from mistakes and fix them. Official releases should be only those
that are tagged as such.
Another problem is that the version is hard-coded into the Ant file.
So, if anyone checks in a change without changing the version number
in the build file, the build generates JARs with the same version
number as a previous release. Anyone checking out the trunk and
building it themselves gets an incorrect version number.That's why I
changed the version number in the build file to X.X.X-snapshot, to
indicate that this version being built is not an official release.
I think that a JAR with a release version number should only be
produced by an official release build, not by a "developer" build
performed by checking out and running Ant on a developer's box. And
even building a tagged release should generate JARs that are marked as
a developer build in their version number.
--Nat
Derek Mahar
> 2008/10/3 Derek Mahar <derek...@gmail.com>:
>> By changing the version number you effectively made a release that
>> warrants a new tag. How else could we checkout this version again?
> In that case the release and versioning process is broken.
>
> Anything in trunk is not a release by definition. Checking in to
> trunk should *not* be the same as an official release. People make
> mistakes. That's why we use version control -- to let us back out
> from mistakes and fix them. Official releases should be only those
> that are tagged as such.
Let me rephrase my previous statement. By changing the version
number, you *started* a new version that you intended to subsequently
tag before you incremented the version number again. The new version
number marks the start of the version and and the tag marks the end of
the changes to that version. If you look back in the history, you'll
see that this is the process that I was following.
After creating the tag, one need not make an "official" release (i.e.
make the new versioned jarfiles available for download), but this is
usually what I did. Even if you don't build a release, the tag does
serve to mark the version if you ever want to build it again or
release it later. You created version 1.4.0, but did not create a tag
before you changed the version to 2.0.0. Even though you didn't make
an official release of 1.4.0, the tag is still important.
> Another problem is that the version is hard-coded into the Ant file.
> So, if anyone checks in a change without changing the version number
> in the build file, the build generates JARs with the same version
> number as a previous release. Anyone checking out the trunk and
> building it themselves gets an incorrect version number.That's why I
> changed the version number in the build file to X.X.X-snapshot, to
> indicate that this version being built is not an official release.
When someone builds the trunk, they the version number is the version
of the next release. I agree that having the same development and
release version numbers may cause some confusion, but not that much.
I'm in favour of adding a qualifier like "-dev" or "-snapshot" to make
it explicit that the trunk version is under development. We would
then remove the qualifier from the version number before applying the
tag (and optionally building a release).
If we don't place the version number in the Ant build file, how do you
propose that we supply the version number to the Ant build? Should we
pass it on the command line? Store it in an environment variable? I
still think that it should be in the Ant build file or a build
properties file. That way, we save the user from having to provide
the version number every time he or she runs the build.
> I think that a JAR with a release version number should only be
> produced by an official release build, not by a "developer" build
> performed by checking out and running Ant on a developer's box. And
> even building a tagged release should generate JARs that are marked as
> a developer build in their version number.
We could make that distinction by introducing a target that does not
apply the version number prefix, but I prefer using a qualifier in the
version number to distinguish between a developer and release build.
Derek
Nat Pryce
>
> On Fri, Oct 3, 2008 at 2:54 AM, Nat Pryce <nat....@gmail.com> wrote:
>> 2008/10/3 Derek Mahar <derek...@gmail.com>:
>>> By changing the version number you effectively made a release that
>>> warrants a new tag. How else could we checkout this version again?
>
>> In that case the release and versioning process is broken.
>>
>> Anything in trunk is not a release by definition. Checking in to
>> trunk should *not* be the same as an official release. People make
>> mistakes. That's why we use version control -- to let us back out
>> from mistakes and fix them. Official releases should be only those
>> that are tagged as such.
>
> Let me rephrase my previous statement. By changing the version
> number, you *started* a new version that you intended to subsequently
> tag before you incremented the version number again. The new version
> number marks the start of the version and and the tag marks the end of
> the changes to that version. If you look back in the history, you'll
> see that this is the process that I was following.
>
> After creating the tag, one need not make an "official" release (i.e.
> make the new versioned jarfiles available for download), but this is
> usually what I did. Even if you don't build a release, the tag does
> serve to mark the version if you ever want to build it again or
> release it later. You created version 1.4.0, but did not create a tag
> before you changed the version to 2.0.0. Even though you didn't make
> an official release of 1.4.0, the tag is still important.
A tag is what defines a release. To do a release, one tags what is
about to be released and then builds any distribution packages from
the tag. One does not release from the trunk and then tag after the
fact.
Trunk is unstable work-in-progress *by definition*. That means that
any changes to the buildfiles and elsewhere have no significance.
Only a tag has significance.
I put 1.4.0 into the buildfile becaue I realised that I had made
changes but the build was creating packages identified as 1.3.0, which
was incorrect, because 1.3.0 had already been released. However, I
then realised that the buildfile did not distinguish between
development snapshots and released versions, so added the "-snapshot"
suffix. Then, when I made a change that was not backward compatible I
bumped the version to 2.0.0-snapshot.
> When someone builds the trunk, they the version number is the version
> of the next release.
Then changing the version number in trunk is *not* the same as
defining a new version. It is merely indicating that the trunk is no
longer the same as the last released version. If the work in the
trunk breaks backward compatability, it may need to be changed again,
from a minor increment to a major increment. Which is what I did.
> I agree that having the same development and
> release version numbers may cause some confusion, but not that much.
> I'm in favour of adding a qualifier like "-dev" or "-snapshot" to make
> it explicit that the trunk version is under development. We would
> then remove the qualifier from the version number before applying the
> tag (and optionally building a release).
>
> If we don't place the version number in the Ant build file, how do you
> propose that we supply the version number to the Ant build? Should we
> pass it on the command line? Store it in an environment variable? I
> still think that it should be in the Ant build file or a build
> properties file. That way, we save the user from having to provide
> the version number every time he or she runs the build.
If the user is doing a build, then they should not get the same
version number as an officially packaged binary release. If user
builds and official builds have the same number it becomes very
difficult to work out what version and what build environment bugs are
reported against.
Here's how I've done releases on other library projects.
The trunk is always unstable. Versions are created by tagging the
trunk when it is considered stable. I usually have a script checked
in that creates a version tag from the working copy if there are no
changes and the code being tagged passes tests and other validation
steps.
Making that tag *is* releasing a version. Once a version has been
tagged it cannot be changed. If the release was a mistake, it can
only be fixed by tagging another release with a larger version number.
A released version may be packaged for distribution. Again, I usually
have a script checked in to do this. The packaging script checks out
a version's tag, compiles, tests and creates distributable packages
and then publishes them on a webserver etc. The packaging script
passes the version number to the Ant build, which uses it in the names
of JAR, zip and tgz files it creates.
If run normally (not by the packaging script), the build defines the
version as "SNAPSHOT", and maybe include the branch and timestamp in
the version ID. That way, a build made by a developer is clearly
distinct from one that was made by the official release process.
--Nat
Nat Pryce
of releases as described below. If nobody has any objections I'll
test them out by making a 2.0.0-RC1 release.
--Nat
2008/10/3 Nat Pryce <nat....@gmail.com>:
Derek Mahar
>> On Fri, Oct 3, 2008 at 2:54 AM, Nat Pryce <nat....@gmail.com> wrote:
> A tag is what defines a release. To do a release, one tags what is
> about to be released and then builds any distribution packages from
> the tag. One does not release from the trunk and then tag after the
> fact.
This is exactly what I did. I did not build any binary release from
the trunk directly, but from a tag.
Unfortunately, however, a Subversion tag is not the perfect definition
of a release. The problem is that unlike with CVS or Git, Subversion
allows one to commit new revisions on a tag just like on a branch or
the trunk. So, like the trunk, a Subversion tag does not guarantee
that a binary build of a tag is identical to a previous binary build
from that same tag. If you built and released binary packages from
two different revisions on the same tag, then you released two
different versions having the same tag.
> Trunk is unstable work-in-progress *by definition*. That means that
> any changes to the buildfiles and elsewhere have no significance.
> Only a tag has significance.
This may be true of projects to which you have contributed and is so
far true for Squiggle, but it is not a general rule for all projects.
For example, what if the convention is to ensure that every revision
on the trunk is the result of a merge from a branch where all the work
on the next release takes place? The branch would be unstable, but
every new revision on the trunk would represent a stable, tested
revision. Tags would serve only to mark and label the branch merge
point.
> I put 1.4.0 into the buildfile becaue I realised that I had made
> changes but the build was creating packages identified as 1.3.0, which
> was incorrect, because 1.3.0 had already been released. However, I
> then realised that the buildfile did not distinguish between
> development snapshots and released versions, so added the "-snapshot"
> suffix. Then, when I made a change that was not backward compatible I
> bumped the version to 2.0.0-snapshot.
I don't disagree with what you did, but would have preferred that had
created a tag for 1.4.0 before you changed the version to
"2.0.0-snapshot". Was 1.4.0 not significant enough to warrant a tag?
>> When someone builds the trunk, they the version number is the version
>> of the next release.
>
> Then changing the version number in trunk is *not* the same as
> defining a new version. It is merely indicating that the trunk is no
> longer the same as the last released version. If the work in the
> trunk breaks backward compatability, it may need to be changed again,
> from a minor increment to a major increment. Which is what I did.
I agree. I also like to think that the version number represents a
set of revisions that will all be incorporated into a future tag (and
possibly a binary release from that tag). Using a branch would
arguably be a better way to achieve the same result.
> If the user is doing a build, then they should not get the same
> version number as an officially packaged binary release. If user
> builds and official builds have the same number it becomes very
> difficult to work out what version and what build environment bugs are
> reported against.
So why not just always add the "-snapshot" (or "-dev" or "-unstable")
qualifier suffix on the end of the version number? This will ensure
that the trunk version always differs from a release version.
> Here's how I've done releases on other library projects.
>
> The trunk is always unstable. Versions are created by tagging the
> trunk when it is considered stable. I usually have a script checked
> in that creates a version tag from the working copy if there are no
> changes and the code being tagged passes tests and other validation
> steps.
>
> Making that tag *is* releasing a version. Once a version has been
> tagged it cannot be changed. If the release was a mistake, it can
> only be fixed by tagging another release with a larger version number.
This is a perfectly sensible practice, but I also consider it
perfectly acceptable to create a tag of a revision for which one never
actually releases a binary package. Tags can be useful for other
purposes than just making a release, though I agree that that is
purpose for which they are most commonly used.
> A released version may be packaged for distribution. Again, I usually
> have a script checked in to do this. The packaging script checks out
> a version's tag, compiles, tests and creates distributable packages
> and then publishes them on a webserver etc. The packaging script
> passes the version number to the Ant build, which uses it in the names
> of JAR, zip and tgz files it creates.
I think these scripts are useful, but they do assume a particular
development environment which the simple version number embedded in
the Ant build script does not. For example, the script may assume
Linux or Windows, Subversion, Perforce, CVS, or Git. If you change
the development environment, the scripts may no longer function. In
that case, it would be prudent to have the embedded version label as a
fallback.
> If run normally (not by the packaging script), the build defines the
> version as "SNAPSHOT", and maybe include the branch and timestamp in
> the version ID. That way, a build made by a developer is clearly
> distinct from one that was made by the official release process.
I think this, too, is a perfectly good practise. But you still have
not convinced me that the approach of embedding the version number in
the Ant build script is so flawed. It's simple and works well as long
as you don't commit and tag the wrong version label. (You can easily
fix such a mistake by deleting the incorrect tag and creating a
correct one.) Many open source library projects use the same or
similar approach:
SvnAnt
http://subclipse.tigris.org/source/browse/*checkout*/subclipse/trunk/svnant/build.xml?content-type=text%2Fplain&rev=3959
http://subclipse.tigris.org/source/browse/subclipse/tags/svnant/1.0.0-rc1/build.properties?rev=1413&view=markup
Apache Commons Collections
http://svn.apache.org/viewvc/commons/proper/collections/trunk/build.xml?view=co&content-type=text%2Fplain
(uses "version-snapshot" convention)
http://svn.apache.org/viewvc/commons/proper/collections/tags/COLLECTIONS_3_2/build.xml?revision=560660&content-type=text%2Fplain
(removes the "-snapshot" suffix qualifier)
GData Java Client Library
http://code.google.com/p/gdata-java-client/source/browse/trunk/java/build-src/version.properties
http://code.google.com/p/gdata-java-client/source/browse/trunk/java/build-src/core.xml
The GData Java client library is interesting because it is composed of
clients for several different Google services and it does not use any
tags or branches. File "version.properties" defines the version
label of each jarfile associated with a particular application client.
I can only speculate that the reason why the project does not use
tags or branches is so that its source history can stay independent of
any version control system.
I think your approach to handling versions and releases is valid, but
I also see little problem with the approach of embedding a version
number in an Ant build file in order to append it to the name of a
jarfile. It may not be totally foolproof (does such an approach
exist?), but it is simple and works well enough that many open source
projects have adopted it.
Nat Pryce
> I think your approach to handling versions and releases is valid, but
> I also see little problem with the approach of embedding a version
> number in an Ant build file in order to append it to the name of a
> jarfile.
There is no problem if the version number in the build file indicates
the version that is being worked towards. However, that means that
the version number in the build file has no significance, releasewise.
Work that changes the API could require that the version number be
changed before release. E.g. one change may be backward compatible
(minor version increment) and another not be backward compatible
(major version increment).
But if the version number in the build file indicates the version that
*was* released then any change to the trunk makes that version number
invalid and creates incorrect binary packages.
If the convention is the former, then the version number in the build
file in trunk does not indicate what is released and I incremented the
version number to indicate changes to backward compatability, so I'm
not sure what you're complaining about. If the convention is the
latter then there is a problem with the version being in the build
file, so the convention needs to change.
--Nat
Nat Pryce
> I think these scripts are useful, but they do assume a particular
> development environment which the simple version number embedded in
> the Ant build script does not. For example, the script may assume
> Linux or Windows, Subversion, Perforce, CVS, or Git. If you change
> the development environment, the scripts may no longer function. In
> that case, it would be prudent to have the embedded version label as a
> fallback.
If the project is moved to some other VCS, then the tagging and
release process will have to change, but automating it is still a good
idea. Changing a couple of small scripts is not a big deal compared
to converting the project's history to another format.
If you don't develop on Linux, Mac or Windows with Cygwin installed,
feel free to convert the scripts to Ant targets.
--Nat