Version package updates for Elm 0.19

[skarger]

I just updated a package to work with Elm 0.19. The final step is to publish and I have a question about versioning.

In my case the public API has not changed, so elm bump interprets it to be a PATCH level change.

Question: Is it true that in this case, the right approach is to publish a PATCH level change, even though it is in fact a “breaking” change in the sense that the new code will only compile with Elm 0.19?

Additional Notes:

I found this question How to Update Package to 0.19 where @evancz said the following:

The version numbers should just keep going with 0.19, so it looks like your next version should be 2.0.2 or higher.

I’m interpreting that to mean that package versioning is exclusively about the public API. I think I understand the reasoning for that - if the versioning were also used to distinguish compatibility with different Elm versions, it would cause a confusing interaction with the API versioning:

For example, if my current Elm 0.18 package is 3.0.1, and then I bump to version 4.0.0 for Elm 0.19, then what would happen if I wanted to backport a breaking API change to the Elm 0.18 branch? I could not bump it to version 4.0.0, since that MAJOR version is already taken by Elm 0.19. In theory could bump it to 5.0.0, but then we have interleaved MAJOR versions for different Elm versions. A breaking API change for the Elm 0.19 package would then need to go from 4.x to 6.x, and so on. Making sense of the available versions would be difficult for package users.

So limiting versioning to API changes makes sense, but therefore I have no way to signal “If you update this package from version <= 3.0.1 to >= 3.0.2 then you will only be able to compile your project with Elm 0.19.” I think the best I can do is to put that note on the README or CHANGELOG. But it would be great to know if there are other steps to take.

[dmy]

I believe that you can publish the same version for both 0.18 and 0.19, but you will have to keep both sources together (there will be a single git tag):

For example, AFAICT, elm-css 15.0.0 had been published for both 0.18.0 and 0.19.0:

rtfeldman/elm-css 0.15.0 sources

Look at the elm-package.json and elm.json files, the 0.18-src sub-directory and the git tag.

This version can be found both on:

• elm 0.18 packages
• elm 0.19 packages

Note that a minor release has been done after only for 0.19.0 (elm-css 15.1.0).

Edit: I’m not sure though how a new minor version could be released now for both 0.18.0 and 0.19.0 as is should be 15.1.0 for 0.18.0 and 15.2.0 for 0.19.0

[skarger]

Thanks @dmy, I followed the pattern from elm-css. Do you know if and how people should update the Elm 0.18 package repository? elm publish only seems to put it on the official (Elm 0.19) https://package.elm-lang.org/ index.

[dmy]

You have to use the elm-package tool from 0.18. If the package version then appears on https://dmy.github.io/elm-0.18-packages/, publishing succeeded. IIRC it can take a few minutes though.

Note that there is no way AFAIK to see the 0.18 version of the package documentation if you publish the same version on both 0.18 and 0.19. It is therefore strongly advised to have the exact same API (and therefore documentation) to avoid confusing users.