Stabilizing PLR & versioning

there are some things in PLR which have never been rewritten since I first wrote them 1-2 years ago. This means by rewriting we can likely improve those parts a lot.

As an example, @CamilloMoschner has ‘fixed’ the plate definitions, and now they are as good as done.

Another example is @JKH and I recently fixed iswap movements involving rotations on STAR. Highlighting: where we think the api looks good, we need to think about a good test.

We need to start focussing on stability soon, but we can’t be stable with code that is not good. I feel like when we have discussed & tested a part of the code, it’s usually rational and quite stable.

There will obviously be changes we need to make, we are never truly “done”, but they are usually not urgent if the existing version is rational and of good quality.

To track what parts we have ‘finished’ in this sense, what parts are wip, and what parts we need to do still, I created a gsheet:

Let’s add to this the following week and execute asap, targeting the end of the month.

When we have all these parts done, we can release version 0.2 (version 0.1 being ill-defined, dating aug '22-now, oct 5 '24). For changes after, we will keep track of how breaking they are and schedule them for releases in cycles.

Until the end of the month, we maintain high velocity (move fast and break things) to get ready.

2 Likes

when deciding your versioning scheme, “zero versioning” maybe a nice thing https://0ver.org/

2 Likes

As a alternative to SemVer or 0ver, using a calendar based release number (CalVer) might be a option. Eg. 2024.10.0 for the first release in October 2024. Using the whole year as first number makes it clear that it’s calendar based versioned. One drawback of this is that migrating to a new versioning schema might be more complex (but there is something called epoch which could be used).

We do use CalVer based versioning (for internal packages):

  • When new features are as important as breaking changes. In PLR this could be the addition of new resources.
  • When it’s hard to tell if a change might be a breaking change for some of the users
  • We won’t use CalVer for drivers as those should get more and more stable and the scope and number of features stabilize as times goes by
  • It’s easy to reason about how old a release is. If someone is using version 2022.1.0 I immediately know that they are using a old release.

Just my 2 ¢.

2 Likes
  1. what happens if you need to update a bug the same day something is released
  2. how does this distinguish between breaking changes and patches?
  1. If you released 2024.11.0 today and found a bug with a quickfix, just release 2024.11.1. The last digit is not the day but a incremental number within the month.

  2. It does not. But what is a breaking change? If I fix a position of a resource, is it a breaking change?