Implement versioning, changelogs, and more

[raulk]

Package/crate versions

Currently all our crates carry Cargo version v0.1.0, and our contracts module carries v0.0.1 in package.json. We haven't published/released packages/crates to public registries yet. IPC is designed to be used as a set of binaries at present, so it's probably not worth to publish to registries since we don't expect devs to adopt IPC through dependency management tools.

Instead, it's preferrable to wait until the IPC framework can be integrated as library (see #1010). I'm happy to be convinced otherwise, e.g. if devs/users make a case that publishing all or some crates/modules at this stage would be beneficial regardless. If so, please shout out in comments!

Product revisions

I'd like to introduce the notion of product revisions immediately. Product revisions are global tags in our repo, accompanied by a changelog, (possibly) precompiled binaries, and release comms. In the future, a product revision will be a coordinated crate release.

Product generations

We expect IPC to evolve heavily in the next months. Every major architectural iteration and major innovation motivates a new product generation. Examples of architectural changes reflected as new generations:

• Modularizing the IPC framework (Modularizing the IPC framework #1010).
• Decoupling from CometBFT and introducing pluggable consensus.
• IPC contracts redesign (Contract redesign #931).
• Wasm IPC actors.
• Introducing a dynamic client that can validate multiple subnets at once.

We could techically represent each of these major product iterations as major versions, but we'd then lose the ability to convey breaking changes within an iteration (assuming the semver paradigm). So I conclude we need a higher entity that can be assimilated to a "channel" or a "long-term branch".

Naming. The idea is to pick a theme and name generations lexicographically with terms from that theme, e.g. tree names, world volcanoes, etc. We'd namespace our crates and modules with the generation name (e.g. ipc_aliso_crypto; Aliso is a tree species), resetting the semver version. Upgrading a downstream codebase from one generation to another would involve updating dependencies to new crate names and versions. One major downside is that it leaks onto third party libraries, since they'd need to release crates for each IPC generation they're compatible with.

On backwards compatibility. While the IPC team will strive to retain backwards compatibility across generations, this is impossible to guarantee a priori. On the other hand, IPC is too early in its lifetime to become ossified. However, the IPC team remains committed to providing upgrade paths with every new product generation, with as little disruption/impact as possible. We will partner with adopters to migrate them to newer IPC generations as they become available.

Conventional commits

A fairly easy win is to adopt conventional commits together with tools like commitlint, or GitHub Actions to enforce the convention.

Changelogs

For every product revision, we'd produce a changelog using an automated tool like https://github.com/conventional-changelog/conventional-changelog, and enhance the changelog with notes on protocol-level compatibility, upgrade considerations, and hard fork expectations.

[raulk]

@folex @sanderpick @cryptoAtwill would appreciate your comments on the above. I suspect the concept/logistics of product generations might be the most controversial element, but we could experiment with it and easily back out if it creates too much pain.

[folex]

Thanks for pinging me!

Interesting approach with generations. I'd love to see how that plays out!

I also like the version reset flow. Fresh start every time 🙂

Renaming crates might be bit tough for the IPC team, because you would need to rename all the inter-dependencies in your own Cargo.toml's, and possibly imports, too.

Though Cargo makes it's possible to decouple crate import name from the dependency name, I hope that will make dev team's life easier.

Otherwise, looks pretty well thought-out.

[raulk]

Though Cargo makes it's possible to decouple crate import name from the dependency name, I hope that will make dev team's life easier.

Yep, exactly! The idea would be to alias the dependency to elide the generation name from import statements in code.

[cryptoAtwill]

I feel the decoupling of cometbft is very interesting, but also very difficult. It's another big big refactor. The current App is basically an ABCI, either we change ABCI or change external consensus to use ABCI framework, the former is easier. But if this is done, it's really cool.

[sanderpick]

Thanks @raulk! This looks great. The idea of product generations makes sense to me.

Unrelated, is there a place to follow ideas on these generations?

• Wasm IPC actors.
• Introducing a dynamic client that can validate multiple subnets at once.