search

malariagen / malariagen-data-python

Analyse MalariaGEN data from Python
https://malariagen.github.io/malariagen-data-python/latest/
MIT License
13 stars 23 forks source link

Switch to calver #323

Open alimanfoo opened 1 year ago

alimanfoo commented 1 year ago

I'm not sure how useful it is to follow strict semver here, given the breadth of the API across different data resources. I propose switching to calver, using a YYYY.0M.0D scheme.

leehart commented 1 year ago

CalVer might release developers from the discipline of bumping the major version whenever the API isn't strictly backwards-compatible, if that's actually being honoured, but then the advantage of API users knowing when to expect API breakage is lost. I can appreciate that this discipline becomes harder, or impractical, to maintain as the API grows in breadth. I wonder if breaking the API into submodules with their own SemVer is an option, although I can imagine that might just make matters worse.

CalVer might be easier for the developers to follow, as a labelling practice, and simple enough for API users to understand. The change of "contract" would then imply: your code (use of this API) might break at any time, whenever you dare to upgrade, and we make no promises about backwards compatibility. This might already be the status quo, so switching to CalVer might be a natural fit.

Perhaps the best of both worlds might be achievable if there is some sort of dedication to Long Term Support, or if backwards-compatibility promises are given, perhaps based on YYYY or 0M. But that might create an odd situation where you hold off releasing any changes this month, or this year, e.g. if you promised that all January releases would be compatible.

I suppose it depends, to some extent, on how the users are using the API, and the details of the new scheme, but if strict SemVer is proving a pain, and it's not worth it, then why make things harder than they need to be!

Personally I suspect any difficulty in applying strict SemVer might point to some other code-organisational issue, like when a function or a module gets too big or too complicated. There might be tools out there (akin to changesets) to help aggregate versions, for example. In any case, if SemVer is proving unhelpful, then perhaps CalVer might be a reasonable fit for this particular thing, at this point in time. I doubt changing the versioning system at this point would cause too many headaches. Wasn't there talk of changing the package name as well though? Perhaps both changes could coincide.

alimanfoo commented 1 year ago

Thanks @leehart.

CalVer might release developers from the discipline of bumping the major version whenever the API isn't strictly backwards-compatible, if that's actually being honoured, but then the advantage of API users knowing when to expect API breakage is lost.

Yeah, that's the downside. But it becomes a bit grey because if following strict semver (as we have been so far) means even the smallest change in backwards-compatibility (like removing an obscure parameter in a single function that hardly anyone ever uses) requires a major version bump.

Perhaps the best of both worlds might be achievable if there is some sort of dedication to Long Term Support, or if backwards-compatibility promises are given, perhaps based on YYYY or 0M. But that might create an odd situation where you hold off releasing any changes this month, or this year, e.g. if you promised that all January releases would be compatible.

Can see the attraction, but kinda feeling like it could get complicated and we don't have the bandwidth for that at the moment.

CalVer might be easier for the developers to follow, as a labelling practice, and simple enough for API users to understand. The change of "contract" would then imply: your code (use of this API) might break at any time, whenever you dare to upgrade, and we make no promises about backwards compatibility.

Yes that's basically what we would be switching to.

Personally I think that would be fine. I don't think we have any users currently who are making use of the fact that we follow semver.

If a user wants to make their analysis reproducible, the best bet will always be for them to pin malariagen_data to a specific exact version. In that case it doesn't matter for the user whether we're using semver or calver.