Resolve toolkit versioning

[ddebrunner]

Be good to get guidelines on how to version toolkits, otherwise it's likely that multiple different copies of the toolkit will exist with the same version number, as commits are made and people copy the code without using a "formal" release.

https://github.com/IBMStreams/toolkits/wiki/Toolkit-Versions

[hildrum]

I think your second option (odd numbers are in development, even numbers considered stable) sounds good.

We have no control over what people do with version numbers in their copies, but we should try to follow some sensible scheme in the ones under IBMStreams.

[chanskw]

I think having odd / even numbers to identify whether something is stable or not is confusing. I think we need to publicly declare if a toolkit is stable.. e.g. providing stable build and links to it in our web pages.

And bumping on each commit seems like an overkill. I expect clients to use the version range in their info.xml to control which version to use as their dependency.

Here's the versioning guidelines used so far. In my opinion, a toolkit should have a 3 digit version, plus a qualifier that represents a build date. On a day-to-day development perspective, if we have continuous build, the build date should be bumped automatically, by the build process. The version of the toolkit remains unchanged.

e.g 1.0.0.v20140325

At some point in time, we will decide that a toolkit is "stable" and ready to be released. We will bump the version number on the first change of the toolkit (after it is declared stable). Typically, at the end of a "release", we will review all changes in each toolkit and decide if additional version bump is required based on all the changes that are made.

How the version is bumped should be determined what is changed in the toolkit.

A toolkit version contains 3 digits. Changes to each of the digits represent what's changed in the toolkit. The assumption we make here is that user will specify dependencies like this in their applications: [1.0.0, 2.0.0) - i.e. from 1.0.0 to 2.0.0 (exclusive)

1. If the toolkit only contains minor fixes, bump the 3rd digit
2. If the toolkit contains significant new functions, but it will continue to be compatible with previous version, bumb the 2nd digit
3. If the toolkit contains incompatible changes, bump the first digit.

We may need to leave room for maintenance as the toolkit is changed. For example, if the first release of the toolkit is 1.0.0... and in the development stream, we need to make a minor change to the toolkit. Based on the guideline, we need to bump the 3rd digit. But in order for us to represent changes in for maintenance in the 1.0.0 stream, we will need to leave room in the 3rd digit of the version number. So in this case here, the version number for the next release will need to be changed to 1.0.100... any changes for maintaining the 1.0.0 stream can bump the version number to 1.0.1.

[hildrum]

I think many/most people are going to get these toolkits by cloning the repository from github. So, they'll never see or know about the 1.0.0.v20140325--all they'll have is what's in the info.xml file.

Maybe we could follow Samantha's suggestion, but have a "version" file at the top level in the repository that contains the date and time of the last commit? We could make a commit hook so that this file is updated automatically anytime someone commits to the repository.

[chanskw]

I think we have two types of users:

1. Toolkit developers - who will clone projects and build themselves
2. Toolkit Users - customers who want to get the most up-to-date changes from the toolkit

We need to tailor for both types of users.

To clarify things a bit, I am not suggesting that the info.xml will contain the qualifier. I envision that the info.xml will have something like this as the version:

1.0.0.$qualifier

where the qualifier is just a variable. The build process will replace the qualifier variable with the build date to produce a built toolkit.

So, the developer will see 1.0.0.$qualifier in the info.xml. The toolkit user will get 1.0.0.v20140325 in the info.xml when they download the build output.

[hildrum]

I think even toolkit users who want an up-to-date version will be likely to clone the toolkit.

Provided the compiler doesn't choke on 1.0.0.v20140325, I think that sort of version in the info.xml is a good idea. I think it would be better if it were the date of the last commit, though, rather than the last build.

[ddebrunner]

I've issues recently with rapid development of a toolkit and ensuring people were on the same version, so I think this needs to be reflected in the three digits, as I'm not sure the compiler or SPLDOC supports a fourth element. May just have to try.

[ddebrunner]

And a toolkit has a location for the version, in the info.xml file, so there's no need to have an additional version file.

[mikespicer]

I'm not keen on bumping the version automatically based on commits. I think of the version number as the release number and that is how I'd expect people to use it in dependencies etc. During rapid development where people are using an in development toolkit I think a build id is more useful for detecting if its the same build. In the case where someone has cloned a toolkit and done their own build then we really have not control over the version number but an automatically generated build id could identify if its an "official release" or a private build that may or may not have changed. The build id could include a timestamp or last commit or similar to reliably identify if anything has changed compared to an official release or other build with the same release version.

[ddebrunner]

One issue might be that the version is in the info.xml which is source, so a build would require modifying a source file, which then increases the risk of it being committed accidentally. It also get copied into the toolkit.xml which is generated, but SPLDOC looks at info.xml.

[ddebrunner]

Here's images of what SPLDOC looks like with a build date in the version number with two approaches:

Just the date and time

Adding a keyword to make it easier to read

[hildrum]

@mikespicer I think we should have something with a timestamp and a date to keep track of between-version versions. I don't have any preference between including in the info.xml as part of the version, in info.xml as a separate field (as a comment?), or as a separate file.

I think we should based this on the last change to the repository (either a date-timestamp, or a hash of the HEAD at that time, which is what git uses to identify a particular version, or possibly both) rather than when it was built.

@ddebrunner If we choose to include it in the info.xml as part of the version, I prefer it with the keyword.

[ddebrunner]

@ejpring wrote in the wiki:

Personally, I like the convention Eclipse uses of appending the build date to version numbers. I imagine this would be straight-forward to implement in the Streams compiler, but then there would be a lot of changes needed in Streams Studio and the documentation.

[ddebrunner]

So the general consensus seems to be use some form of build identifier in the version.

The SPL compiler, SPLDOC support it (maybe SPLDOC could be improved to handle the build cleanly). It seems Streams Studio supports it, so techincally we seem good to go.

With streamsx.inet I'm going to try and see how it would work, given the version is stored in the info.xml which is of cource checked into git.

@mikespicer the bulld identifier must be in the version number, rather than as a comment, to make it obvious (easy to determine) which build is being used. E.g. in Streams Studio it will be obvious from the version next to the project name, rather having to ask people to look elsewhere.

[mikespicer]

I like the idea of having the build identifier in the version so it can easily be seen but want to clarify if this is a convenience to easily see or if it will be a significant part of the version which we will take action on. I think our version resolution should ignore it and a user would set dependencies based on the version number without the build identifier. I like the example above of version 1.0.0 build 201403291123 as it clearly differentiates the build identifier rather than the dot notation which just makes it look like a part of the release version.

[ejpring]

For me, its just a convenience to label builds with a timestamp. I'd like the compiler store the build timestamp somewhere, maybe in 'info.xml', and I'd like Studio to display the build timestamp somewhere, maybe following the version number. But I would not expect either to use the build timestamp when resolving dependencies.

[ddebrunner]

To be clear, the version definition in Streams supports a.b.c.buildIdentifier.

That is, it's the format of the version in info.xml.

How tooling displays it is a separate issue, both SPLDOC and StreamsStudio could be enhanced to separate the build identifier visually.

[ejpring]

I'm confused. I looked in the 'info.xml' files for some of my SPL projects, and they all have something like this:

<info:version>1.0.0</info:version>

The 'Edit Toolkit Information...' dialog in Studio seems to have a pattern constraint on the 'Toolkit version' field, something like '<major.minor.qual.build>', but its not clear to me what constitutes a valid 'build' value. For example,

I think you're suggesting that the compiler could automatically update the 'build' value of the version field with a timestamp, and Studio could format a version field of 'a.b.c.d' for display as '[a.b.c build d]'. Is that the right idea?

[petenicholls]

I believe the consensus is to use the 4th qualifier as a build id in the toolkit version.

The 4th qualifier is ignored during toolkit dependency resolution so it will not affect that.

I do not believe there is a mechanism in place now where the toolkit build will automatically update the info.xml file with a build identifier.

The problem with the above is likely the blank space.

[ddebrunner]

@ejpring I'm just saying what the format of the version number should be.

Next it needs to be worked out how to achieve that with SPL toolkits under IBMStreams in github.

It's also tied into how to make these toolkits consumable for users. Currently this site is not suitable for people who just want to download and use a toolkit, but it's just getting started.

[ejpring]

I think the README.md box and the 'Download ZIP' button on the home page of each repository is all people really need, if they just want to download and use a toolkit. I've seen prettier front-ends for GitHub that hide all the other stuff on repository home pages. Is that what you had in mind?

[ddebrunner]

I thinking of a direct access to a toolkit download for people who just want to use a toolkit, without them having to figure out a README, type ant, make or spl-make-toolkit, or realize the toolkit is not at the top-level. The repository is a source repository, not a useable toolkit.

Take a look at the streamsx.inet pages that @hildrum set up. While the downloads are currently just archives of the repository, the look and feel is must better for toolkit consumers, including the SPLDOC for the toolkit and its samples:

http://ibmstreams.github.io/streamsx.inet/

[ejpring]

Yes, that's the pretty front-end I flashed by a few days ago. How'd you do that?

[hildrum]

@ejpring The web page is very easy to setup, just follow directions for a project page here: https://pages.github.com/ The only problem is that I think most of us don't have permissions on the IBMStreams repositories to do the initial setup (I tried it out on my fork for streams.inet initially). It was @chanskw who made original page for streams.inet.

Those download buttons are part of what comes when you create the web page, but the problem is that they give you the whole repository, unbuilt, so people are still going to need to run ant or make.

I have a script I'm working on for generating & updating the spl-doc, so while I don't see a way to make that fully automatic at the moment, I think it will be minimally painful. (See IBMStreams/streamsx.inet #23.)

[ddebrunner]

FYI - I have a working top-level build.xml in streamsx.inet that creates a tar bundle for a toolkit including setting the build identifier based upon the the commit hash.

The quick summary is I changed the committed info.xml to to have a __dev__ build identifier, and then ant replaces it with the commit hash. Here's what the build version looks like in SPLDOC:

Described in IBMStreams/streamsx.inet#30

[ddebrunner]

I also found out github has a release mechanism:

https://github.com/blog/1547-release-your-software

So I tested out the process (it's very easy) in streamsx.inet and created a pre-release:

https://github.com/IBMStreams/streamsx.inet/releases

It just uses the binary artifacts created by the release target in the top-level build.xml of streamsx.inet

[hildrum]

I think there's agreement that our version numbers on our releases should follow the semantic versioning guidelines. The question is how to treat latest-and-greatest version in the repository--we know what x.y.z means on a release, but what does it mean when it's on the head of the master branch of the repository?

I propose we treat master branch of the repository as an alpha version of the represented release. (Or some other word that indicates pre-release if you don't like "alpha".) If the latest in the repository has version x.y.z, if we were to tar up the repository and give it a version number, it'd be x.y.z-alpha.tgz.

• This means, generally, that the version in the head of the repository will be x.y.0, since you don't usually have patch levels on pre-release versions.
• When release x.y.0 is created, update either x or y, depending on what your planned changes require.
• If you need to make a bug fix on x.y.z, and it's not enough to direct people to the repository version (which will be either x.(y+1).0 or (x+1).0.0), then you make the fix starting from the branch for x.y.z. The fix will have version x.y.(z+1), and a corresponding branch will be created.

[ddebrunner]

It what I setup at streams.inet the tag was underscore dev underscore to indicate development. I don't think '-' will be allowed, something complained when I tried some other character to clearly delineate the marker.

Note some toolkits may decide on a mode of the master is always releasable and stable, that's seems to be an approach becoming more common. It's definitely a faster way to get functionality into users' hands. The github release mechanism will allow this without having to create branches for releases since it automatically creates a tag for a release. I assume a branch could be created as needed for any specific tag.

I'd probably prefer the master is always releasable approach, maybe after the first full release (non-pre release), thus master could have a version number like 1.2.4, as bug fixes can be made on the master and released.

However, I think it will be up to the committers of a project, guidelines can be provided for different approaches, but I don' think a single approach can be mandated.

[hildrum]

I think the master should be always "release-able" in the sense that it should work.

But I don't think it makes sense to update the minor version on every new function delivered to the master, which would be what semantic versioning would require. I also don't think it's practical to update the patch with every single commit or every push.

Let's say I decide to add a new set of features. Before I start, the version is x.y.z. After I'm done, is the version x.(y+n).m where n is the number of features in that set, and m the number of bugs I found after pushing the last feature? Or is it x.(y+1).0? I think the latter makes more sense.

What I was proposing was that we update it to x.(y+1).0 on the first push for that set of features, and then when the committers think that set of features is done, make a release.

[ddebrunner]

Always releaseable means just that, at anytime the master is a release, not that it's "workable" and after some time of fixing etc. a release is made. What you are describing is a traditional release cycle. Both are valid approaches.

http://guide.continuousdelivery.com/continuous-delivery/

[hildrum]

I am all for continuous delivery in practice. But we have these version numbers fields, and I want to fill them out in a way that makes sense. What are you proposing as a version numbering system that works well with continuous delivery system?

[ddebrunner]

This blog post says:
If you want to use Continuous Deployment (or Delivery) with Semantic Versioning, the assignment of a new version number is a programmer decision.

http://blog.ploeh.dk/2013/12/10/semantic-versioning-with-continuous-deployment/

Which means it's a decision a committer has to make on each commit or accept of a pull request, the version is bumped according to the type of the change.

[chanskw]

I'd like to close on this.

I think it is a toolkit's committers team's decision on how to version and maintain their toolkits. i.e. IBMStreams administration should not mandate how this has to be done. However, I think having some general guidelines is useful.

I propose the following guidelines:

A toolkit version contains 3 digits. Changes to each of the digits represent what are changed in the toolkit. The assumption we make here is that user will specify dependencies like this in their applications: [1.0.0, 2.0.0) - i.e. from 1.0.0 to 2.0.0 (exclusive)

1. If the toolkit only contains minor fixes, bump the 3rd digit.
2. If the toolkit contains significant new functions, but it will continue to be compatible with previous version, bumb the 2nd digit
3. If the toolkit contains incompatible changes, bump the first digit.

I believe this is the minimum guideline for toolkit versioning. Each toolkit repository should document their versioning strategy or simply refer to the wiki if they decide to follow this guideline.

e.g. If a repository wants to implement the qualifier approach, they are free to do so. The minimum is that every toolkit release should require a version bump to identify what changes are made.

Please +1 on this proposal if you agree, and I can update the wiki.
Please -1 if you have any concern.

I propose to leave voting for 1 week. If there is no objection, I will also update the wiki.

Thanks!

[mikespicer]

+1 I would also be more explicit and add that 2 releases with different code should not have the same version number.

[chanskw]

Thanks Mike! I agree... will add that.

[ddebrunner]

Minor nit: "A toolkit version contains 3 digits and a qualifier".

[ddebrunner]

The wiki should also reference:

http://www.ibm.com/support/knowledgecenter/SSCRJU_4.0.0/com.ibm.streams.dev.doc/doc/versioningguidelines.html?lang=en

Which basically says the same thing.

[ddebrunner]

I think it is a toolkit's committers team's decision on how to version and maintain their toolkits
IBMStreams administration should not mandate how this has to be done

I'm not so sure, any other scheme is likely to confuse users of the toolkit.

Also the project incubation page says: "Project ... follows semantic versioning (http://semver.org/)"
https://github.com/IBMStreams/administration/wiki/Project-Incubation-Process

What flexibility might a project have while still being a toolkit that can be used easily by others?

Are you proposing the incubation policy will change or that a toolkit can have a different scheme but won't be able to graduate?

[chanskw]

I think we are in agreement that toolkits should follow the semantic versioning guidelines.

So, let me rephrase this.

Here's what we are going to state:
It is the toolkit's committers team's decision on how to version and maintain their toolkits. It is highly recommended that they follow the semantic versioning guidelines as documented. Following this guideline is a requirement for a project to graduate from incubation.

My thoughts on this:

1. This is a guideline that people need to learn and understand. Prior to graduation, toolkit project may be more relaxed in how they manage their versions. It may not be clear, but it is something the project team needs to learn and develop on.

2. I think each project has different requirements and details on how to actually implement the versioning guidelines. I do not think we can mandate the exact detail on how this is done, but we need to ensure that version numbers are bumped and reflect what's changed. We also should make sure that the projects document how they have implemented the guideline.

Sound ok?

[chanskw]

I updated this page:
https://github.com/IBMStreams/administration/wiki/Toolkit-Versions

If you disagree, please update the page directly and we can discuss. I hope we are close to closing this.

Thanks!

[chanskw]

Closing this one... please open new issue if we need more discussions.