v1 of things

[achingbrain]

We should release v1 of most things*.

Right now everything is 0.x.0 which means we only have minor and patch releases available to us and according to semver 0.7.0 is incompatible with 0.8.0.

This has led to the situation in js-ipfs where after an npm install you currently get 26 (26!) copies of multihashing-async in your node_modules folder, because ipfs depends on 0.8.0 and most other modules depend on 0.7.0.

Because we don't automatically pull these new versions in, a lot of busywork is created** to manage the cascade of releases required to keep everything up to date and in this case the change between [email protected] and [email protected] was a new feature so it's a problem entirely of our own making.

We could release bug fixes and new features as 0.x.x releases, but now we're just making the rules up as we go along.

Semver is obviously not a magic bullet, we may accidentally release breaking changes as minors in the future but it seems weird to deny ourselves the opportunity to get it right, particularly when we have lots of modules with relatively stable APIs.

---

* = primarily anything that isn't a top-level project (e.g. js-ipfs, js-libp2p, js-ipld) though even then,
would it be so bad? ipfs-http-client is on v40 and no-one seems to be complaining.
** = Greenkeeper/dependabot can help here but the volume of updates can be high and the modules still have be manually released***
*** = GitHub actions**** can help here but the modules still have to be released in a specific order
**** = why are we inventing so much infrastructure and process when we could just use semver?

cc @ipfs/wg-js-core and @ipfs/repos-javascript

[alanshaw]

Yeah, we just need to do this now. This is actively hurting our credibility in the JS ecosystem by not communicating properly what expectations users can have about new releases, it’s bloating our bundle size (as evidenced above), and causing many wasted hours of dependency babysitting.

We should stay pre-1.0 for top level dependencies (as suggested) to avoid giving the wider world the impression that js-ipfs/libp2p/ipld are ready for production but where possible we should rev other dependencies to 1.0 unless there is a really good reason not to.

@hugomrdias @jacobheun @vasco-santos @vmx @mikeal @rvagg @lidel @daviddias do we have your agreement?

@achingbrain if we reach consensus then please turn this issue into an awesome endeavour and list the ipfs dependencies we want to 1.0 so we can track progress.

IPLD and libp2p folks it would be useful if you added your lists here too!?!

We also need to write a blog post as part of this endeavour that we can point people to in case of questions and so this doesn’t come unexpectedly to people.

[vasco-santos]

I am totally up for this! 🚀 I feel this is a good timing after finishing the async refactor

[hugomrdias]

Yep let's do it.

[jacobheun]

👍 I am very in favor of this. I am also in favor of including top level projects.

Associating semver to project state (alpha, beta, production ready, etc) is a mistake, imo. Those two are disparate and shouldn't be directly associated. Documentation and project descriptions should reflect the state of the project, and may point to semver ranges for clarity, but project state shouldn't be inferred by semver.

I know the top level projects have been a point of contention, so I'd rather concede there if need be and get the low level dependencies upgraded.

[daviddias]

I'm in favor of this, yet I would like to see the list of what are "most things*" first before saying yes right away. @achingbrain can you list the modules that you are looking to bring to v1?

Also, as highlighted by #2222 and #2446, it is time to reduce our module granularity. Lot's of work done by the libp2p team so far, would love to see some on ipfs as well.

[momack2]

Agree w all the above (but agree we need to keep top-level js-ipfs 0.x.0 until we’re ready to commit to interfaces). @Stebalien - I think this also needs your tech lead eyes to make sure no unintended consequences :)

[achingbrain]

can you list the modules that you are looking to bring to v1

I mean, basically all of them

If you are a Lead Maintainer of a module, take a look at it. Has the API been stable for the last, I don't know, six months? Was the last release ages ago? Is it being used in production? By more than one module? Maybe one outside IPFS/libp2p? If the answer to two or more of these questions is 'yes' it's probably time for v1.

it is time to reduce our module granularity

I totally agree and will get moving on this once the mammoth async iterator PRs are merged.

[Stebalien]

Rust FYI: almost all rust crates use sub-zero minor versions like major versions. Non-breaking features are often released in patch releases.

That aside, I agree (and defer to @alanshaw as the lead maintainer). We need to 1.0 more things (just not js-ipfs itself).

[lidel]

As a data point for this discussion,
I was looking at all the BREAKING API CHANGES in release notes for js-ipfs 0.41: #2656

Pretty intense changeset for a generic version number.
Maybe we should jump to 0.50 🙃

[achingbrain]

We've started releasing V1 of things, hooray! I don't think we need this issue any more.