Fedimint's Backwards-(In)Compatible Philosophy

[bradleystachurski]

The documentation in version.rs does a good job of explaining the different types of versions (core consensus, module consensus, and API versions), however I haven't been able to find documentation on the project's philosohpy for introducing changes in a either a backwards-compatible or incompatible way.

• If we need to introduce a change, do we prefer backwards-compatibility?
• Is that preference the same for core consensus, module consensensus, and API changes?
• How will we manage parallel changes that are backwards-compatible and breaking?
  • e.g. v0.2.0 was just released; if there's a backwards-compatible API change and a breaking core consensus change, will we merge both of these changes into master and cherry-pick commits into separate release branches for v0.2.1 and v0.3.0?

[elsirion]

From 0.2.0 on we want to guarantee two things to remain compatible:

1. The server with its previous version, i.e. we want to guarantee that a fedimintd-v0.2.0 when upgraded to v0.3.0 or v0.2.x will start again and function normally from a user PoV.

• Internally it may run DB migrations that make it impossible to go back to the previous version
• It is still unclear if we want to support skipping "major" versions (currently, since our versions all start with 0, I call x in 0.x.y the major version).
• The guarantees for minor versions are a bit less clear. Because of Rust SemVer we have to keep rust interfaces compatible, but apart from that we can decide if we e.g. want to guarantee downgradeability.

2. The client with past and future versions of Fedimint

• A v0.2.0 should be able to talk to v0.2.1 and v0.3.x federations.
• A future v0.3.x client should still be able to talk to v0.2.x federations
• We probably don't want to guarantee this kind of compatibility forever, so we'll have to decide on a support window.
  • Shorter support windows help us keep our code clean, longer ones reduce pressure on integrators and users to upgrade
  • We should likely have a mixed time and version based guarantee: compatibility till the first major release at least x months after the client version became out-of-date. That way increasing the release cycle would not lead to surprise incompatibilities.

[dpc]

Version numbers are basically free, let's just bump the relevant ones for each PR.

Which version numbers? We can code, consensus, db (server + client), api versions to worry about. :D

For consensus we are running INT::MAX for master and incrementing each release(?), IIRC - that was a conclusion some time ago.

[douglaz]

We're gonna need perhaps a devimint feature where you can replace the client or the server or any component with a different version (older or newer) then run all the tests and see if they pass.

[bradleystachurski]

Good call, created an issue to track: #3962

[douglaz]

@elsirion master has already broken the compatibility (gateway /info now is a GET instead of a POST)

[elsirion]

😢 yeah, we need tests asap. In this case we need to add back the POST version and mark is as "deprecated after version x" and then track when we can remove it eventually.

[bradleystachurski]

Thanks for the thorough response!

[dpc]

BTW. Do we even have client side db migrations implemented? @elsirion

[m1sterc001guy]

Unless I missed something recently, I do not think we have client side migrations.

[dpc]

Migrations on the client side might be even more important than on the server side because there is more clients, there are less technical and it's harder to use multiple clients for the end user and migrate than for guardians. @m1sterc001guy

It might be harder to implement architecturally because state machines are created and encoded by module but stored outside of it by the global executor/client. But it's definitely doable.