When publishing a typst package, the guidelines say package-versioning should follow SemVer, which I have two questions about:
typst still being in version 0.x.y, and frequently introducing breaking changes (which is not bad!), is it permitted to publish a package with major version larger than 0?
As brought up in a discussion for CeTZ, if a package has major version 0 and publishes breaking changes, only incrementing the patch version is SemVer-compliant. However, many software-systems, e.g. cargo, extend the SemVer-spec by saying that, while in version 0.y.z, increments in the y-version can be treated as major releases (breaking changes), and increments in the z-version can be treated as minor releases. In version 0.0.z, incrementing z is always a major release. Would it make sense to adopt a similar rule for typst packages?
Regarding the second question – rant incoming: I treat my own packages (which are all 0.x so far) like cargo and try to avoid breaking changes in patch version changes. It’s important to remember that Semver is only a convention; if we as a community de facto conform to that interpretation, that becomes what Typst package versions mean. Likewise, if we use three-component versions but don’t adhere to semver, there’s no tool inherently stopping us from doing so (but let’s hope we don’t go there).
And since it’s tangentially relevant: package versions (currently) can’t specify pre-releases, etc., so Typst does not implement full semver anyway.
Typst’s stance on compatibility is (currently) more strict anyway: you have to always specify full package versions. What would be a “non-breaking change” to a programmer may be a breaking change to an author; let’s say changing some font size. Suddenly your pages look horrible because a paragraph takes an extra line. So you could argue that Typst ignores Semver’s definition of compatibility anyway.
</rant>
To come back to your question more directly:
I personally adopted that rule, and while I don’t know about others’ intentions, the Typst ecosystem broadly feels like this. I’m not sure if we really need to formalize this, since I’m not sure what practical difference it would make. Two reasons against it I can see would be 1) package authors are open source authors, and I wouldn’t want to force this rule on someone who feels it’s a nuisance to them, and 2) if a package is unpredictable with breaking changes, that may impact its adoption anyway, so I think that creates enough regulation on its own.
Typst is in its 0 major version, so any change is fine, moreover changelog always documents all breaking changes. The packages on the other hand, well I would assume that any visual change is breaking, because of the nature of documents. So if a package treats such changes as not breaking, then that’s the package’s fault. Typst catching strays out of nowhere.
P.S. Using Tytanic will quickly show you what is a breaking change and what isn’t. Which is a great tool to use anyway.
I’m aware of all that. I was just saying, since the package repo says “Package versioning should follow SemVer.”*, the fact that Typst doesn’t use semver compatibility could be considered a mismatch between the docs (that sentence) and what Typst actually does.
*actually I misremembered and thought that the statement was stronger, something like “Typst uses SemVer for packages”, in which case that hypothetical criticism would make a bit more sense.
Currently, if a package is on version 0.x.y, increments in x carry no further specified meaning compared to increments in y. If x>0, then breaking changes can be published, despite only incrementing y. Again, such an action is semver-compliant, but not compliant with e.g. cargo’s semver-rules.
A practical difference is that, when updating your packages, you might expect – and I did, when updating CeTZ – that a package updating from 0.3.2 to 0.3.3 does not introduce any breaking API-changes. CeTZ did have a (small) breaking change, which surprised me.
“Visual-changes are breaking-changes” is a good point. I can imagine people having different intuitions about that, some agreeing that it’s a breaking-change while others disagreeing. If I open an issue in the typst-package-repo about semver, I should bring that up as well. Thank you all!
I just want to note: the reality is that packages can be released that break either semver’s or cargo-style-semver’s compatibility conventions. This is true for Universe (where a review for breaking changes would be infeasible), as well as for crates.io (where no review happens). The difference is that, since Cargo resolves crate versions, users will notice the breaking changes without having changed anything.
So to state my opinion bluntly: since Typst does not resolve compatible versions, what we declare these versions to mean doesn’t matter that much. That’s what I meant by saying “I’m not sure what practical difference it would make.”
With all that said, yes that would surprise me too. I understand people who are reluctant to go beyond major version 1, 2, 3 and thus we have zerover, but I don’t see much reason to shy away from 0.4, 0.5, 0.6, so I would just follow the cargo conventions. But in the end, since updating depencencies in Typst is manual, I do it relatively deliberately, and stumbling over a breaking change is not something that worries me too much. I see it this way: if I don’t need a new feature, I can simply not upgrade. And if I do need it, I need to fix breakage no matter what the version number introducing that feature is.