Version scheme and release management

[michaelsauter]

Initially, we decided to do "something like Semantic Versioning" for ODS. I think this is a bad fit because:

• IMHO, Semantic Versioning only works for libraries. It does not work for products or platforms (which is what ODS is). When you have so many moving parts, guaranteeing that some change will not be breaking for some users is almost impossible - so basically you are forced to always update the major version. And that conflicts with the perception of "normal users": A big new feature might update the minor version, but a bugfix might update the major version. That is weird.
• In practice, we do not follow Semantic Versioning so far, so we should not say that we do
• Using Semantic Versioning makes it impossible to know what the next version will be. This has huge implications: e.g. the quickstarters on master point to production of the shared-library - only on a branch such as 1.2.x we point to 1.2.x. That is super annoying for users tracking master in their Bitbucket installation because all provisioned quickstarters are bound to break eventually. If one would know the next version number, the situation would improve a lot: one can set the pointer to the "next version" on master directly after a release. This also makes it easy to merge between branches ...

So, my suggestion / recommendation is:

Move to a simpler version scheme where we only have one big number. Similar to what Chrome does. Concrete: The next release should be "OpenDevStack 2" in my opinion, and the one after "OpenDevStack 3". We can have an additional patch number if needed but that is in my eyes a detail only. A "minor version" would not exist - there would be no ODS 2.1 etc.

Further, I propose to have relatively fixed dates when we release - I suggest to target one release early March and one release early November. By using plain numbers we are not bound to release exactly in those months but I still believe it would be beneficial to us to have more fixed dates. That would mean that ODS 3 is released in May 2020 and ODS 4 released in November 2020.

@clemensutschig @tjaeschke @rattermeyer @stitakis @metmajer Please share your views.

[rattermeyer]

I completely agree with @michaelsauter observations. What probably could be an alternative versioning is 20.1 and 20.2, denoting the first and second release, with patch number only if it really is required 20.1.1 for example. this is similar to what ubuntu is using (although they have the month 19.04, 19.10). ODS 3 and 4 would probably communicate more of a radical change, than clearly saying, we simply have two releaseses each year.

[michaelsauter]

@rattermeyer Cool.

My concern with 20.1 and 20.2 is that it forces you to actually make the second release within the year because you will already assume that version number in master.

Chrome seems to get away with just incrementing the numbers. I think with lower numbers, e.g. 2 to 3, it sounds like a big change, but once you are at 8, 9, 10, 11 and so on it is obvious that we are not necessarily taking about huge changes.

[rattermeyer]

simply incrementing is definitively easier. For me it would be ok as well. The simpler the better.

[tjaeschke]

I agree with both of you, that SemVer doesn't fit. I'm with @michaelsauter. We should just increment.

[metmajer]

Good observation @michaelsauter, and I am generally fine with some overall non-SemVer based versioning (see below). Having major numbers only and releasing only twice per year leaves the impression that there is no room for rolling out minor, yet important, adaptations in between.

However, from what I can anticipate, I expect releases to happen at least twice as often as indicated by you. I see various drivers for change and value is not created in Git. Also, since it is planned that our team will handle releases in the future (lucky you ;-), I expect you can be more flexible about the release cadence :)

Most importantly, not all components have the same maturity level and therefore shouldn't be thrown into the same bucket. ODS is definitely not Chrome, but a collection of components provided and often maintained by different groups of contributors. Our users should be aware of the fact that some of those components are still early stage (and by no means enterprise-ready).

That said, I would support the notion of a major version for OpenDevStack, as it is an umbrella project and each version would indicate the "next big splash". Components should have their own version, and if their maintainers prefer to use SemVer, then so be it.

[michaelsauter]

@metmajer I am a bit confused about your comment ...

1. I think many enterprises will not be able to handle more than two actual updates on their end, so releasing more often does not necessarily help. Related to that - with "Also, since it is planned that our team will handle releases in the future" you mean performing the upgrade of an ODS installation or the release on Github?

2. Having different versions schemes for ODS components sound confusing to me. ODS is already confusing, we should simplify things. Personally, I would love to move more things into one repo and therefore we would only have one version. In order to be versioned differently, I think the thing to be versioned must be a standalone tool (e.g. like Tailor). What I think is possible though is that the quickstarters will be versioned independently in the future once they have been separated from the core properly and only need to advertise the compatibility with ODS. So if your comment about "flexible version scheme for components" was in regards to quickstarters, I can see the possibility too.

[tjaeschke]

I'm not sure, if moving more things to one repo would really ease the handling.

I think we should reduce the ux complexity by providing more utilities that ease the handling. I like the way docker goes to have a separate repo for the installation script. In our case you would download an start the script and this will clone the necessary repos and install the stack, unattended with a configuration file or with user inteactions if the user wants to. I'm now at the point to say, ok let's use Selenium or mechanize to automate the atlassian tool installation, even if we have to adapt ui changes.

Additionally I think from an user perspective it's not intuitive to run a script from a repo subdirectory to install something, but we should discuss this separatly.

[michaelsauter]

Oh moving things into one repo I support because:

• For new users, that many repos is confusing (e.g. where is stuff located, where do I open an issue on Github, etc.)
• Many repos = many things to do Git actions in (e.g. tagging, branching etc.), also sometimes one needs more than one PR to achieve one change because the change affects multiple repos

I think that in the ods-core repo, one could have:

• the prov app
• document service
• all the project related stuff from ods-project-quickstarters
• sample config

So what you'd be left with is just:

• core (including install scripts would be my preference, but we can discuss separately)
• jenkins libraries (2 repos, for speed of clone in Jenkins build - but maybe there is another way to fetch it?)
• quickstarters (which is good to have separate as there might be many repos containing ODS quickstarters)

[tjaeschke]

I see, just a misunderstanding from my side, sorry. I had also the PMC and github.io repos in mind.

• core
• libs
• quickstarters

sounds good to me.

[michaelsauter]

This is in place. It should be documented though, which is tracked at https://github.com/opendevstack/ods-core/issues/511.