👩‍💻 Proposed notes on versioning for contributors

[fwkoch]

This PR is an attempt to slightly formalize my answer to this: https://github.com/jupyter-book/mystmd/pull/1650#issuecomment-2485557941

I'm totally open to feedback here - this is just the general rules I personally follow when bumping versions (and I always try to avoid any changes that don't just fall under patch...).

These rules are different from "official" semantic versioning which is basically - major: any breaking change, minor: any feature, patch: bugfix. But I'd argue in favor of maintaining the distinction between user-facing breaking change vs. developer-facing breaking change. (Possibly this suggests we should have different versioning on mystmd - "user-facing" - and myst-cli - "dev-facing" - where breaking changes can imply different levels of impact...)

[changeset-bot[bot]]

⚠️ No Changeset found

Latest commit: 3350d3de9187e5d2b431eb0a9d388acb070109a4

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[choldgraf]

For what it's worth, I'd be keen on trying out Jacob Tomlinson's effver approach, which I've found to more naturally map onto the ways that devs think about versioning their code. It is basically semver, but with the guiding question.being "how much effort would it likely take your target user to upgrade?".

That said I'm not sure how it works in practice so I don't feel super strongly about this. It might also be hard to weigh whether we are thinking about author users or developer users (eg of plugins etc). Maybe that's a jupyter book vs myst distinction?

https://jacobtomlinson.dev/effver/

[agoose77]

@choldgraf I think that definitely would be a better candidate for Jupyter Book over MyST, as it's solely an application. And, FWIW, I like the idea of interrogating our use of semver -- I encourage calver normally because I think semver is pretty hard to do communicate in a meaningful sense to all users.

calver vs effver is a fun conversation to have; calver solves semver problems by saying "consult our docs to learn about when we'll plan to break things", whereas effver is a lot more hand-wavy. For that reason, I'm a lot more pro-calver in general.

[agoose77]

@fwkoch I like this PR. If you are happy that it represents the current state of thinking on your part and Rowan's, then let's merge?