Community
Participate
Working Groups
In our maintenance/SR releases we treated API additions as rare exceptions and feature work was almost never approved. Therefore we never increased the minor version for those releases, but suppressed the API Tools error to increase the minor version. Now, with the new Update releases, where API and feature additions come more often, we need to decide whether we continue with the above approach, or be honest and use accurate semantic version numbers. Our Version Numbering wiki page (https://wiki.eclipse.org/Version_Numbering#When_to_change_the_minor_segment) already provides some guidance on this: Also, when the minor segment is incremented in a maintenance stream, you must increment the minor segment again in the next stream. For example, if plug-in P has version 2.2.7 in the 1.0 product release, it would increment to 2.3.0 in the 1.0.1 product release, and 2.4.0 in the 1.1 product release. Incrementing the minor segment in a maintenance release after there has been a release in a future stream cannot be done unless you have left a gap in your version numbers to leave room for it. Besides the drawback already mentioned above / in the wiki, a bigger one is that after increasing the minor version in the update branch the committer must not forget to increase it in the master branch. I would like to propose another solution for which we can easily add support in API Tools: - When an API or feature is added the first time in master, we no longer increase the minor version by 1 but by 5. This leaves room for our 3 update releases plus a potential additional update after the new main release has been shipped. - When an API or feature is added in the update release the first time, we increment the minor version by 1. - API Tools will issue corresponding errors and offer quick fixes to make the correct increase. This will be done by using a new workspace preference that allows to set the minor version increment.
My 2 cents: The benefit of increasing the minor with API changes is marking that API usable for clients. It is accompanied by an "@since x.y" in the code, and clients who use that API will update their minimum required version on a dependency in the MANIFEST.MF. We still have a policy that new features / APIs are introduced in master first (and may be backported). We also have a policy that new APIs need soak time, in order to make sure they are really the right thing and maintainable in the future. I do not feel very comfortable saying "you can use that API in Oxygen.2 but it is not in Oxygen.1". And I am also not very comfortable shortening the API soak time / review cycle. So from my POV, if a new feature/API is backported from master into a Service release, I would stick to just updating the service number. In other words, the new API would be there, and "friends" or close consumers could use it if they are comfortable adding a requires on the specific 3rd digit version of the bundle. But the API would not be marked as officially usable in the service release, and there would be no promise keeping the backported (service only) new API stable. I would even go as far as marking any backported API in API tooling with @noreference this API was backported as work in progress and may change moving forward Bottomline: Service releases could add user-visible features/functionality, but would usually not add consumable API for extenders. That part would still be for yearly releases only.
(In reply to Martin Oberhuber from comment #1) > Bottomline: Service releases could add user-visible features/functionality, > but would usually not add consumable API for extenders. That part would > still be for yearly releases only. Speaking of the main release (master), adding UI/features also mandates an increase of the minor version. This allows products that no new stuff sneaks into their product just by upgrading to a new Update/SR release. The same should apply when we now add features (or API) to Update releases, hence my vote would be to increase the minor version in Update releases.
My real preference would be to have a single development stream that always increased the segments based on standard semantic versioning rules. This at least gives the consumer the ability to decide whether or not they want to take the new release based on accurate information. I've never liked the "leave a gap to allow for maintenance streams" etc., but if we can't get rid of the multiple streams problem, lets at least increment by, say, 10, so we don't have to worry whether we're going to run out.
(In reply to McQ Wilson from comment #3) > I've never liked the "leave a gap to allow for maintenance streams" etc., > but if we can't get rid of the multiple streams problem, lets at least > increment by, say, 10, so we don't have to worry whether we're going to run > out. I'm fine using 10 instead of 5.
I didn't read all wiki page about Version Number. But I would like to share this link with you. http://semver.org/
(In reply to McQ Wilson from comment #3) > My real preference would be to have a single development stream that always > increased the segments based on standard semantic versioning rules. This at > least gives the consumer the ability to decide whether or not they want to > take the new release based on accurate information. I was about to write a similar comment when I saw this one and I fully agree with that. My observation: if we allow to have new features or API additions in Eclipse SDK contributed to so called Update Releases of the Simultaneous Release then we should decide what is an update release for Eclipse SDK. If adding new API or new feature with proper version increment according to semantic versioning is allowed for an update release, then we should increase also the version of the whole Eclipse SDK accordingly, e.g from 4.6 to 4.7 for the same update release. And this brings us to the point where we should question the existence of maintenance branches for Eclipse SDK in its current form if maintenance branches can have all bug fixes and per-request API changes backported. In such case, the overhead related to deciding on proper workarounds for versioning scheme (whether to add 5 or 10) and maintaining proper versioning for 2 streams that can literally contain the same code is a waste of time. Having one stream like McQ proposed would be much easier and allow to avoid 1) inventing new workarounds for versioning scheme, 2) maintaining master and maintenance branches where the distinction between them would be very vague, 3) allowing committers to make error-prone changes with versioning which can be very hard to overcome by end users if released unnoticed.
(In reply to Szymon Ptaszkiewicz from comment #6) > (In reply to McQ Wilson from comment #3) > > My real preference would be to have a single development stream that always > > increased the segments based on standard semantic versioning rules. This at > > least gives the consumer the ability to decide whether or not they want to > > take the new release based on accurate information. > > I was about to write a similar comment when I saw this one and I fully agree > with that. When we discussed the meaning of the Neon Update releases for the Platform the PMC agreed that API changes and new features are still the exception for the Platform and the focus is on stability (see https://wiki.eclipse.org/Eclipse/PMC#Meeting_Minutes). With this, it's clear that we need two streams.
(In reply to Dani Megert from comment #7) > (In reply to Szymon Ptaszkiewicz from comment #6) > > (In reply to McQ Wilson from comment #3) > > > My real preference would be to have a single development stream that always > > > increased the segments based on standard semantic versioning rules. This at > > > least gives the consumer the ability to decide whether or not they want to > > > take the new release based on accurate information. > > > > I was about to write a similar comment when I saw this one and I fully agree > > with that. > > When we discussed the meaning of the Neon Update releases for the Platform > the PMC agreed that API changes and new features are still the exception for > the Platform and the focus is on stability (see > https://wiki.eclipse.org/Eclipse/PMC#Meeting_Minutes). With this, it's clear > that we need two streams. I see. So what about propagating bundle's version increment all the way up to the Eclipse SDK version? How this should work if a bundle increases its minor version for an update release? Right now we suppress it by not increasing bundle's minor version, so if we start to increase bundle's minor version but avoid to increase feature or Eclipse SDK version we will have the same problem but in a different place.
(In reply to Szymon Ptaszkiewicz from comment #8) > I see. So what about propagating bundle's version increment all the way up > to the Eclipse SDK version? How this should work if a bundle increases its > minor version for an update release? Right now we suppress it by not > increasing bundle's minor version, so if we start to increase bundle's minor > version but avoid to increase feature or Eclipse SDK version we will have > the same problem but in a different place. You raise a good point. The features versions are defined by https://wiki.eclipse.org/Version_Numbering#Versioning_features, so according to that we might end up with an SDK version of 4.17 for Oxygen. This would be very misleading, since we speak about Oxygen (4.7). Thinking of it again, keeping the status quo as described at the beginning of comment 0 and also preferred by Martin, seems to be a better and easier to handle approach.
+1 for keeping status quo
In our PMC meeting today we decided to keep the status quo, which means no minor version increase for update releases. In case new API is added, the PDE API Tools error needs to be suppressed.
