Replies: 21 comments
-
Thanks for the article. It has some valid points and I agree with its stance on SemVer. So much so that when updating dependencies of my own projects, I not only read changelogs but sometimes even diffs. After all, if a version change is a tldr for a changelog, a changelog is a tldr for a series of commits.
If only more developers were as brave as you to admit this. 😄 CalVer does sound nice. But what do you mean by |
Beta Was this translation helpful? Give feedback.
-
That's all I meant by it, e.g if we aim for ~4 "big" releases a year, then a "patch" is just a small release in between. But I am open to any/all other ideas here. We could have it mean "commits since last
FWIW I think there are classes of projects where it can be successful, those that: are very small, have few/no dependencies, are basically just functions w/o side effects. But Bokeh is not that. :) To really, truly, actually try to make promises we'd have to test for:
And then for that huge matrix have tens of thousands of unit tests, thousands of example tests, hundreds of integration tests, dozens of entire downstream project test suites, untold image diff tests... the resources required are just in a different galaxy. |
Beta Was this translation helpful? Give feedback.
-
Sounds good to me. A "commits in total" would also work if you're OK with potentially large numbers. Just as an example of such numbers: https://github.com/clojure/tools.deps.alpha/releases |
Beta Was this translation helpful? Give feedback.
-
I'm not personally a huge fan of big numbers in versions, especially since our numbers would be even larger, also we may want to release off previous branches occasionally. So I'd lean personally lean towards "meaninless incrementing integer" or "commits since last 'big' version". |
Beta Was this translation helpful? Give feedback.
-
I'd also like to make it clear that I do think the aspiration of maintaining compatibility should be a "north star" for our work. I don't think we should make breaking changes casually. I do think we should strive to be intentional, with deprecation periods and communicating detailed information about changes. But occasionally more sudden changes are warranted, and often changes slip in w/o consideration. So this is really just about recognizing that reality. |
Beta Was this translation helpful? Give feedback.
-
Absolutely. Sometimes people even go as far as avoiding incompatible changes altogether by introducing new packages (similar how it's happening in Go, according to that article). It might be something to consider as well - having |
Beta Was this translation helpful? Give feedback.
-
Also for reference, here is the discussion on the Dask tracker: dask/community#100 |
Beta Was this translation helpful? Give feedback.
-
To me calendar-based versioning schemes seem awkward, if the release schedule is not bound to the calendar. So, Ubuntu's YY.MM (e.g. 20.04) is fine, but otherwise both
In this scheme, every feature/API/etc. has a life span assigned as an integer interval So much for an ad-hoc, idealistic definition. The point is that we admit that we break things in minor releases (for various reasons) all the time and that won't change. The versioning scheme has to admit that as well and give our users the ability to predict what works and when. |
Beta Was this translation helpful? Give feedback.
-
That's the point - it doesn't matter at all. There's a need to have a version in the format of
This question made me realize that Bokeh supports older versions and backports/creates some fixes. |
Beta Was this translation helpful? Give feedback.
-
Yes and no. This (new-ish) practice is not so much about supporting old branches, as it is about affording some additional flexibility to release more frequently. We have now gotten in to a situation many, many times where our "next" release branch has gotten much bigger than planned, and gets stuck in a state where it cannot be released yet. When this happens we are hamstrung, and this has prevented us from getting important fixes that were already merged out to users in timely fashion. There are really two cadences we need to accommodate:
As a side effect, pushing bug fixes and small updates into point releases on the last release branch allows the "distance" between the last release release branch and the upcoming release branch to be smaller than it otherwise would be (and thus less risky). But the main point to note is that we really only envision issuing those "point" releases on the previous branch up until the next release branch is released. Then point releases on the old branch are done, so i.e it's not really about "supporting" old branches. So as for @mattpap it needs some elaboration with the above in mind. How do we accommodate both long and short term dev loops? Do you propose something like landing all dev on a dedicated perpetual "dev" branch, and periodically cherry picking commits back to |
Beta Was this translation helpful? Give feedback.
-
I guess I should mention, the default option, which is basically just to keep the status quo, but explain clearly that we do not adhere to strict semver. Then I would decribe
|
Beta Was this translation helpful? Give feedback.
-
I would switch to the option offered by mattpap then. Dependency resolution tools impose their own semantics, even if the users don't want it. Changing the major version much more often would decrease any possible effects of those semantics. |
Beta Was this translation helpful? Give feedback.
-
OK here is another proposal. It's similar to @mattpap except intead of perpetual Y=0, it's a perpetual Z=0 So releases are This gives us:
The reason I would prefer this is that bumping Z instead Y makes the version more tedious when having to talk about them with human beings. I'd literally rather people be able to say "ten point two" not "ten point oh point two" Basically this just would shift the current understanding of release levels "up one" i.e. in practice we have been using minor releases as major release, so this would just acknowledge that. I do think we can make small fast-loop minor releases with some frequency that do have an acceptably very low risk of breakage. Right now those are point releases but this would make them minor releases. |
Beta Was this translation helpful? Give feedback.
-
cc: would really love to hear from holoviz folks (@philippjfr @jbednar etc) and dask folks (@quasiben @jsignell etc) |
Beta Was this translation helpful? Give feedback.
-
Dask recently changed to CalVer in December and so far so good. I don't think we've had any complaints and it aligns much more cleanly with what was already happening in practice. This is the format the dask landed on:
This format has the nice features of being a very obvious date and being string sortable. |
Beta Was this translation helpful? Give feedback.
-
There is a separate discussion in dask around the concept of "blessed releases". These would be releases that are far from major changes and therefore less buggy. I think we arrived at noting these releases after the fact in a document rather than trying to fit them into the version scheme. This makes sense for dask because we often don't know ahead of time which releases will be pretty good. It takes a week or two for that to become fully apparent. I'll just note that this is 100% a judgement call, and might not make sense at all for bokeh. ref: dask/community#101 |
Beta Was this translation helpful? Give feedback.
-
Thanks for your comments @jsignell I think a blessed release idea is an interesting one and may definitely make sense if we move away from "semver". Agree that's definitely a post-hoc judgment for the team to make. |
Beta Was this translation helpful? Give feedback.
-
Speaking from a HoloViz perspective, we've now started pinning to the Bokeh minor release, i.e. the latest Panel (and thus HoloViews and hvPlot) releases pin to Bokeh <2.4. Bryan's modification of Mateusz's proposal, i.e. fixing the patch level at 0, makes sense, but we'd then need to pin <3 instead. Either way, we can deal with it. If Bokeh does follow Bryan's suggestion, then non-zero patch levels remain open for the most critical and most minor bugfixes/patches in the rare cases when those are needed. I.e., typically we'd expect to see .0 at the end, acknowledging that any non-trivial release is also a potentially breaking release, but if we had some tiny bugfix to patch onto an existing release then x.y.1, x.y.2, etc. remain available. Seems like that way we'd respect SemVer, acknowledge that it's rare to have a truly non-breaking release, and yet not just give up on everything as CalVer does. E.g. I don't know what we'd do in Panel if Bokeh does CalVer; just pin to the specific version available on the date Panel is released, and accept no future versions? Bryan or Mateusz's proposals seem preferable to that, as it gives us at least some chance of releasing bugfixed Bokeh without having to re-release Panel. |
Beta Was this translation helpful? Give feedback.
-
So I've had a chance to let this marinate on this a bit, and have a few further thoughts. I am feeling less optimistic about a sweeping change like calver, partially because I think it would fall to me to drive that effort and I am just not up to it, given the need to coordinate external tools and resources like BokehJS CDN. There is just alot of technical risk to changing anything build related and it is not worth the stress. However, the above proposals also do not sit perfectly well with me either, because I do think what the "status quo" offers is three distinct levels of signaing: X = huge, very big, definitely breaking, especially visuals, strong need to telegraph "big event" I think having those three levels available to us, regardless of semver, is actually very good. Conversely: I think both @mattpap and my proposals above destroy any possiblility of over having "major major" releases, and I think that is bad. Regarding the "Y" level, some points:
I think maybe an option here is just to continue being judicious, and conservative with respect to normal users, and to also pro-actively work with downstream projects to help keep things coordinated. Which is advised anyway. I guess my position is that we should just adopt the process that works for us regardless of any external considerations, and simply explain that process as clearly and succinctly as possible. I've been trying to think of what simple organizing principle might encompass this, and a discussion here #11152 (comment) did give me a new idea.
What occurred to me was specifically this: I think the "minor bump means no visual changes" is actually exactly the guarantee are best set up to provide with all of our expanded and expanding visual tests. I think we should just not fight against that reality, and embrace and leverage it as our easily explainable criteria. Edit: and in case it was not evident: I think we should be 100% clear, up-front, and transparent that we do not adhere to semver. |
Beta Was this translation helpful? Give feedback.
-
TLDR; I am circled-back at a defense of the status quo, but with a more clearly delineated rationale:
And also with more clearly delineated criteria:
|
Beta Was this translation helpful? Give feedback.
-
cc @mattpap see my last two comments from last month |
Beta Was this translation helpful? Give feedback.
-
Posting this discussion to take the temperature for looking in to adopting a new versioning scheme.
Some comments and issues regarding the latest release have come up, and also this article by Hynek Schlawack was posted today:
https://hynek.me/articles/semver-will-not-save-you/
I really can't argue with much in that article, and in particular note that for Bokeh we are definitely making judgment calls about things from time to time (or more directly: rationalizing why changes don't really merit a major version bump). If I am honest, I would rather stop pretending that we do (or can) adhere to strict semver.
The article links to this review of different calver adoptions:
https://calver.org/
Since we have CDN coordination to consider, perhaps we could/should consider a scheme that is relatively consistent with our current machinery, e.g
YYYY.MM.patch
YY.minor.patch
Thoughts @bokeh/dev?
Beta Was this translation helpful? Give feedback.
All reactions