Why are different @agoric/X packages have different version numbers?

[LuqiPan]

Whereas all @babel/X packages have coordinated version numbers, for example, @babel/core, @babel/parser, and @babel/generator, etc all have version number 7.24.6 published 11 days ago (as of June 4, 2024)

[kriskowal]

Great question. Coordinated versions and independent versions both have their uses and Agoric (including Endo) have historically favored independent versions, though there are cases where coordinated versions for some packages might make sense.

With coordinated versions, the semantics of semantic versions are less precise. All packages in a project will reflect a breaking change with a major version bump, even if the breaking change affects only one package.

Semantic versioning is a contract between package publishers and subscribers that creates a low-friction path for getting new features and patches by clearly communicating when upgrading a package should not require any extra effort. Bumping the major version indicates that upgrading will take more effort, so packages can opt-in when they have time. Ideally, the project will back-port bug fixes and security patches to every major version train that is still in use. This creates a large economic disincentive to bumping the major version for a responsible publisher.

Example: The Endo project is home to both ses and @endo/bundle-source. With coordinated versions, a breaking change to @endo/bundle-source would oblige us to back-port security fixes for ses to another major version train. SES is much more sensitive to the time it takes Agoric and the Endo community to perform responsible disclosure and publication of security patches. By using independent versions, we decouple this concern and we are more free to bump the major version of @endo/bundle-source if need arises.

Independent versioning also allows subscribers to upgrade to the latest and greatest of each of their dependencies incrementally. This makes it much easier to isolate which package inadvertently introduced a breaking change in composition with their application. In a workflow that obliges a subscribing package to update all packages at once, it can be hard to isolate a bug deep in the transitive dependencies.

The benefits of coordinated versions may be acceptable under specific circumstances.

Some projects need to rely on the conceit that some of its exported package interfaces are really internal implementation details that could be changed as long as subscribers only ever use versions that were published together. This can be enforced with peerDependencies in package.json, but I have not seen tooling that automates this. Then, there’s Hyrum’s Law, which is not absolute but cautions that your ecosystem will inevitably come to depend on these internal interfaces. So, I personally dismiss the conceit that this can be done safely.

Example: The packages @endo/patterns, @endo/pass-style, @endo/exo, and to an extent also @endo/captp and @endo/eventual-send form a system where it would be attractive to pretend that some of their interfaces are implementation details that they can change amongst themselves without bumping their major version number, as long as every dependent package uses releases with the same version number. That could be enforced with a very strict peerDependencies clique amongst these, essentially treating all of these packages as a single release artifact. The developer experience might be frustrating since peerDependencies are not a well-worn developer-experience workflow.

But, encouraging people to use co-released packages increases the chances that integration flaws between the packages would have been caught by the project’s own continuous integration. There is always a chance that shearing in the versions will reveal defects the authors can’t experience because they only ever use the latest versions in their working copy for testing. Coordinated versions make this easier to achieve manually, but I would argue that we would need automation for this workflow that doesn’t exist in order to realize this win generally.