Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

version number conventions #5715

Closed
tdhock opened this issue Nov 2, 2023 · 10 comments · Fixed by #5772
Closed

version number conventions #5715

tdhock opened this issue Nov 2, 2023 · 10 comments · Fixed by #5772
Labels
governance Project governance

Comments

@tdhock
Copy link
Member

tdhock commented Nov 2, 2023

as a part of #5676 I would like to discuss conventions we could adopt for version numbers.
As I understand the current system, even number in the third component/place is used for CRAN release (1.14.2 or 1.14.4), and odd number for github/dev code (1.14.1 or 1.14.3).

I would suggest keeping that convention and augmenting it so that patch/hotfix releases (no new features, just fixes to satisfy CRAN requests) can be distinguished from regular/feature releases, and so that versions with new features will have larger version numbers than patch versions. Currently 1.14.9 is dev and 1.14.8 is CRAN, but if we submit a new patch version to CRAN that will be 1.14.10 which can be confusing because that number is greater than the current dev (1.14.9), which actually has more features. To fix that I would suggest increasing the second/minor component of the version number every time there are new features introduced in dev/github master. So current github master could become 1.15.1, and until that is released on CRAN as 1.15.2, we could submit any patch releases that CRAN requests as 1.14.even (1.14.10 or 1.14.12). Then patch releases would always have smaller version numbers than any github or cran versions with new features.

Additionally I would suggest bumping the major version to 2 to indicate the new governance of the project. So after new governance gets adopted, github master would become 2.0.1, and first regular CRAN release using new governance would be 2.0.2 (with patches 2.0.4, 2.0.6, etc). After that first regular CRAN release, github master would become 2.1.1, which would eventually be released to CRAN as 2.1.2 (with patches 2.1.4, 2.1.6, etc).

The only issue I see with this proposal is the lack of x.y.0 versions, which could be confusing to people who may be expecting that?

@jangorecki
Copy link
Member

Currently 1.14.9 is dev and 1.14.8 is CRAN, but if we submit a new patch version to CRAN that will be 1.14.10 which can be confusing because that number is greater than the current dev (1.14.9)

After such patch release to CRAN we would normally increment master to 1.14.11 to avoid this problem. That is how it used to work, and there was never problem about it.

To fix that

Then no fix is needed.

According to what you are proposing + trying to have (a non patch) release each 6 month, we will be then releasing 1.15, 1.16, etc. quite frequently, right? I recall discussion about this kind of versioning but somehow we haven't landed there. That generally make sense, but your suggestion would skip 1.15.0 and release 1.15.2 instead, which I think is not ideal. We can always increment to 1.15.0 from 1.14.51 (or whatever) just before release to CRAN, that is how it used to work.

As for 2.0.0, sounds scary, could be kept for really big breaking changes, rather than just organisational change. But on the other hand maybe it's not bad idea, check what Matt thinks about that.

@AngelFelizR
Copy link

It took me some time to understand the huge difference between version 1.14.9 and version 1.14.8, and when we compare that to the changes from 1.14.6 and 1.14.8, they were just some changes.

To me, it makes more sense to use the first number for breaking changes, the second for new features, and the third number for fixes. Consequently, the dev version could be 1.15.1, then if later you release a new feature to the dev version it could go to 1.16.1. If at that point the dev can go to CRAN, the new fixes would be 1.16.2.

@msummersgill
Copy link

A change in governance and maintainer is not an event that justifies jumping to 2.0. I don't know whether Matt tried to follow any specific versioning guidelines closely - the commendable lack of major breaking changes doesn't give us any concrete examples, with the first CRAN release v1.2 occurring 15 years ago. However, if a user were to take a glance at a guide like SemVer.org, it would be reasonable to assume that incrementing to 2.0 constitutes "incompatible API changes".

I second Jan and Angel that such a version number change should be reserved for an extreme case of breaking changes. (Whether or not such a scenario is even palatable to community remains another question altogether)

@tdhock tdhock added the governance Project governance label Nov 3, 2023
@MichaelChirico
Copy link
Member

I think it's worth noting that the issue with patch releases "looking like" regular releases is hopefully a transient one. Once data.table maintenance is back in "full gear", I'd expect minor patch releases to be exception rather than what has in the past few years become the norm. Especially with the considerable backlog of ready-to-ship PRs we have in queue, all but the most urgent releases can easily be bundled with enough changes to go beyond just a "patch".

Therefore I suggest the status quo works fine for versioning.

I also don't think bumping to 2.0.0 is warranted, but if someone wanted to dig through the CRAN archives we could "easily" check the typical behavior in the R community when changing maintainers. My prior is "major version bump" is not the modal response.

@jangorecki
Copy link
Member

jangorecki commented Nov 7, 2023

@MichaelChirico Regarding status quo.
I was thinking the same while ago, but over the last two years it changed a bit. Now I think it make sense to provide logical distinction between hotfix releases and regular ones. I recall new env var mentioned in devel docs as to be published in 1.14.2, then 1.14.4, and so on. If we just reserve this last number for urgent / out of schedule hotfix releases we will avoid such kind of issues. I like the way that Matt developed version numbering, but there is some practical aspect here as well.
In #5385 (comment) I outlined version numbers according to what we discussed here, but as there is no complete consensus yet I would like to clarify that after 1.15.0, if we move to 1.16.0 or continue 1.15.2...

@jangorecki
Copy link
Member

Shortcoming of the numbers being proposed is numbering on devel version. We don't want to have 1.16.-1 as devel version to be released as 1.16.0. Also 1.15.1 as devel to be released as 1.16.0 feels little bit slippery, but I don't see better option.

@AngelFelizR
Copy link

I think we should reserve the last number for urgent / out of schedule hotfix releases

@msummersgill
Copy link

I've seen a number of projects that use a large special number for the third place (i.e. 1.15.9000) on the "devel" branch, which leaves 1.15.1, 1.15.2, etc free for patches and hotfixes before 1.15.9000 is ready for a release as 1.16.0.

X.x.9000 then also serves as a subtle warning to those paying close attention that "here be dragons" as the code has not been given a fully versioned release.

Maybe an option here?

@jangorecki
Copy link
Member

I've seen a number of projects that use a large special number for the third place (i.e. 1.15.9000) on the "devel" branch, which leaves 1.15.1, 1.15.2, etc free for patches and hotfixes before 1.15.9000 is ready for a release as 1.16.0.

X.x.9000 then also serves as a subtle warning to those paying close attention that "here be dragons" as the code has not been given a fully versioned release.

Maybe an option here?

That sounds very reasonable and solve 1.16.-1 problem. Although I would keep the number uneven, as we used to do to mark devel version. Then 1.15.99 gives space for 49 patch releases.

@MichaelChirico WDYT, could we consider this issue resolved?

after 1.14.10 release we increment master to 1.14.99, then after 1.15.0 we increment master to 1.15.99.
any hotfix branches in the meantime are branched from 1.15.0 (and not the master) and gets 1.15.1 during their (short) development cycle and are being released as 1.15.2. Similarly for 1.15.3, 1.15.5, etc.
That means

  • master is always 1.15.99, 1.16.99, 1.17.99, ...
  • hotfixes are 1.15.1, 1.15.3...
    in both cases when we submit to CRAN we increment by 0.1 and by 0.0.1 respectively

@msummersgill
Copy link

So I went back and double checked, turns out I was mistaken - the projects I was thinking of that followed the "large final number" convention (i.e. the R plotly package) actually append the number to the most recent release - i.e. 1.15.0.9000. If a patch is required to 1.15.0, it would be released as 1.15.1 and the development version number would bump to 1.15.1.9000, Then, when 1.15.1.9000 is ready for release as 1.16.0, the new development version would increment to 1.16.0.9000.

I don't have any objections to Jan's proposal above though. With the thoughtfulness this project has always had with reverse dependencies and avoiding breaking changes, we have the luxury of version numbering conventions being of minimal significance.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
governance Project governance
Projects
None yet
Development

Successfully merging a pull request may close this issue.

5 participants