Elm 1.0 semantic versioning boundary: migrating a 0.19 codebase without breaking package resolution

Question

Elm 1.0 (December 2018) introduced strict semantic versioning for published packages, but the documented compatibility boundary with 0.19 is sharp: code written for 0.19 generally fails to compile under 1.0 because of changes in the HTML renderer, the signal architecture, and the Task/Cmd/Sub type aliases.

The goal is a controlled migration of an existing 0.19 application to 1.0 while keeping dependency resolution predictable. The Elm package manager checks the installed compiler version against each dependency's declared elm-version range in its elm.json and rejects installs outside that range, so a compiler bump alone can make the whole dependency set unresolvable even before source-level API issues appear.

The uncertainty is sequencing: whether to pin and upgrade dependencies first, or migrate source code first, given that some 0.19-era packages may never have published a 1.0-compatible release. There is also no documented automated codemod covering all breaking changes, so the scope of manual edits is unclear.

Is there a recommended order for updating elm.json ranges versus rewriting application code? How should packages with no 1.0-compatible release be handled? Can elm install errors be used to map the full incompatible set upfront?

Tasadduq Burney · Answer

Direct answer
Update the project's elm-version constraint first, run elm install to surface all version blockers, resolve dependencies to 1.0-compatible releases or replace/fork the ones that do not exist, and only then migrate application source code. elm install errors can be used to map the full incompatible set upfront, including transitive dependencies.
Why order matters
Elm 1.0 enforces semantic versioning via the elm-version field in each package's elm.json. The package manager checks the compiler version against every dependency's declared range and rejects installs before any source is compiled. Changing source first does not make an incompatible dependency resolvable.
Steps for this case

Bump the project elm-version
"elm-version": "1.0.0 <= v < 2.0"

Run elm install
Record the error list. It enumerates every package whose elm-version range does not include 1.0, direct and transitive.

Resolve each blocker

Check package.elm-lang.org for a version whose elm-version includes 1.0.0. If found, upgrade the dependency in elm.json.
If no 1.0-compatible version exists, the package cannot be used with Elm 1.0. Options are to fork the package, adjust its elm-version to allow 1.0, and depend on the fork, or replace it with an alternative.

Repeat until elm install succeeds
Elm has no version overrides or lock files; resolution must succeed for all packages.

Migrate source code
With a resolvable graph, compile the entry point and fix source-level breaking changes such as HTML renderer differences, signal architecture changes, and Task/Cmd/Sub type alias changes. A package may be version-compatible yet still require source edits.

Verify
Run a clean build and tests. A successful compile confirms both dependency resolution and source migration are correct.

Packages with no 1.0 release
They must be forked or replaced. Modifying elm-version yourself is only possible via a fork; the original cannot be used with Elm 1.0.

Elm 1.0 semantic versioning boundary: migrating a 0.19 codebase without breaking package resolution

1 answer

Direct answer

Why order matters

Steps for this case

Packages with no 1.0 release

Your perspective belongs here.

0 question comments