Welcome to the first issue of the Fadroma news bulletin! Honestly, we should’ve started publishing this stuff way earlier.
Between CosmWasm, Rust, Node.js, TypeScript, Docker — and all the other bits and pieces that we’re knitting together to establish the new DevEx baseline for the CosmWasm community — there’s plenty of funny shenanigans going on.
We hope we get around to telling some of those stories before they fade from living memory. But for now, let’s start with a quick overview of what’s been cooking these past few weeks.
Shelving legacy versions
Let’s get the chores out of the way first: in our repository, a bunch of branches of our repo, with confusing names (like v3 or v99) have now gained a legacy/ prefix.
Note: having slashes (/) in the names of Git branches — or tags — is not a particularly great idea. Don’t try this at home — prefer a more path-friendly delimiter such as underscore (_).
Why were those branches there in the first place? Fadroma’s project structure, went through a few sizable metamorphoses — until we eventually settled down on the current shape of our polyglot monorepo. (Some of the legacy packages such as @fadroma/client-* and @fadroma/ops-* are still on NPM, even. They will also go away soon.)
We even tried a Calendar Versioning scheme at one point (think 23.09.x, like NixOS or Ubuntu). Turns out Cargo and NPM don’t have good support for that, at all. For a while, we even entertained the the crazy idea of seamlessly switching from CalVer to SemVer by making our first stable release version 23.0.0 (as in 2023, get it?). Thankfully, all that confusion is in the past. And good riddance! Let’s leave the crazy version number backflips to the browsers and operating systems.
We’re committed to making the most of Semantic Versioning. This means not being afraid to increment the major version when there are breaking changes to API or to behavior. Indeed, our @fadroma/scrt module for supporting Secret Network has already reached version 10.x.x, and we find nothing wrong with that 🙂
In the future, we plan to be even more strict about major versions and breaking changes. Of course, this doesn’t mean incrementing major versions every other week; it means avoiding breaking changes unless absolutely necessary — and staying within the boundaries of the existing API as much as possible.
Version zero forever?
We consider staying on version 0.x forever (like a lot of crucial tooling and foundational libraries unfortunately do) to be somewhat irresponsible: 0.x versioning means downstream developers wouldn’t know when they need to modify their code to accommodate an upgraded dependency. This is a source of uncertainty, confusion and lack of maintenance.
Trouble is, people like round numbers, and can be quite accustomed to version numbers as part of a software product’s branding. So we just weren’t sure when to release 1.0.0, especially considering 1.0.1 would soon follow… Thankfully, Secret Network Proposal #183 provided us with funding to publish a stable version, and we’ve been officially on the radar ever since.
In the meantime, we did publish nearly a hundred 1.0.0-rc.x versions as we stabilized our single-command onboarding through npx. (Surprise surprise, NPM doesn’t have great support for the -rc. suffixes — even though they’re part of the official Semantic Versioning spec.)
Besides, testing an onboarding workflow that goes through an external service such as NPM isn’t a great experience — as we kept finding out all the way up to the following news item.
Someone who is doing versioning right
OKP4 brings Prolog-based Governance as a Service to the world of CosmWasm. It’s great to see their smart contracts starting from v1.0.0 at the outset — and they maintain documentation for all versions of the API. Way to go, folks!
Disclaimer: we lent them a hand with improving the usability of the docs 🙂
The will to do things correctly and completely goes a long way!
Caret versions can be a blessing — or a curse
Those were a major source of silent breakage when initializing Fadroma projects through our npx @hackbg/fadroma@latest create entrypoint. We finally identified and resolved it — hopefully putting issues like this one in the past.
If, like us, you’re a heavy user of multi-package workspaces, careful there: even if you boast an extensive test suite, it probably doesn’t cover how NPM resolves the dependencies between your packages, does it?
So, if a broken a patch version of one of your libs ever gets through all the way to the NPM package repository, the caret ranges (^x.y.z) that package.json helpfully supports may propagate the error back to older versions of other packages that depend on it. Oops, and ouch.
In the future, we hope to speed up and automating our package publishing procedures — which, surprise surprise, become more of a bottleneck the more packages you publish.
And yet more fun with NPM, Node and TypeScript…
We miss CommonJS dearly — but ESM is the future of JS, and we’re helping to bring it about. That can’t happen fast enough — unless we take up maintaining some forks.
So far, the case of RPC bindings proved trickiest. These are automatically generated by protobuf.js, and both @cosmjs/stargate and secretjs contain them, in order to be able to talk to the chain nodes.
Protobuf.js is written in CommonJS. Node.js and TypeScript each address the problem of loading CommonJS code from ESM code independently. And, of course, their individual backwards compatibility solutions have proven to be a little… wait for it… mutually incompatible.
Let’s just say we’re not surprised in the slightest. In our next bulletin, we’ll give you more details on what that fuss was all about — and what we did to resolve it.
Stay tuned, follow us on Medium, and give our tooling a try:
npx @hackbg/fadroma@1.4.12 createwill set you up with a new project.- Documentation is available at https://fadroma.tech/
- We can be reached at hello@fadroma.tech.
Until next time!
