refactor: improvements to the release process

[alanshaw]

This is an updated release process for JS IPFS that has been largely based on the new Go IPFS release process.

It adds a release document to explain the process, adds an early testers programme and updates the release issue template.

This isn't a huge change to what we do already but does more formally specify time frames and stages. I think it makes sense to keep these very similar between the two implementations even if there are some context specific tweaks.

17th September is 6 weeks since the 0.37 release. So we should have kicked off the process on the 27th August. I've started the release issue for 0.38 (and I'd also like your input into what to include in it) but I vote we kick off this new process as soon as we reach agreement on this PR and it is merged. Monday 9th September is day 0

[alanshaw]

js-ipfs currently has no deployments to internal infrastructure so there's nothing to partially roll out to here yet.

[daviddias]

Not itself, but it does rely on *-star signalling servers, preload nodes, relay nodes and bootstrappers

[alanshaw]

If success then I'd like for @lidel to publish a new version of companion to a beta channel 🙏

[lidel]

I wonder if we should include ipfs-postmsg-proxy as a separate thing. Thoughts?

[alanshaw]

Yes I think we should but I think it needs a big update before we can include it here....

[alanshaw]

A bit onerous to keep up to date, but I imagine we can easily just add a new one to this list if we notice one we forgot to add while it was being created...

[alanshaw]

Eventually I'll find time to turn this into an easy to use CLI tool like I did here: https://github.com/filecoin-project/filecoin-contributors

[alanshaw]

Added the 48 hours which the go-ipfs release process doc currently doesn't have. This communicates expectations for when the new release is due and will help with planning of included features. The community could even suggest inclusions.

[momack2]

@Stebalien not sure if you want to adopt this idea too (might help with writing release notes as we go?)

[alanshaw]

This is what we do now. Is this working for everyone? Do we think that with the more strict release schedule we could actually use MINOR for all features (and breaks) and PATCH exclusively for bug fixes?

[jacobheun]

I think this is reasonable with a 6 week release cycle.

[alanshaw]

I think this is reasonable with a 6 week release cycle.

Just to clarify, you are voting for a change from what we do now to this?:

MINOR for all features (and breaks) and PATCH exclusively for bug fixes?

[jacobheun]

Just to clarify, you are voting for a change from what we do now to this?

Yes, I'm in favor of keeping the versioning simple and predictable. It also allows us to minimize the time investment on releases, and ensure that all new features have gone through the full release testing cycle, which should help reduce the need for patch releases.

[mikeal]

This still isn’t going to conform to any of the tooling people have written around semver. Regardless of what we say, developers and the automation written by those developers will tend to assume that there aren’t intentional breaking changes between these releases — or they will assume that any version will break and may not adopt it because there isn’t any kind of guarantee.

I don’t see why we can’t just bump the major version number. Version numbers are essentially free, we have 2,147,483,647 of them available.

We like to talk about “1.0” as this big milestone, but we could just call that milestone something else and untangle it from version numbers. Version numbers, especially in JS, have a lot of expectations around them that we are not currently conforming to. It’s easier to adjust to the community than to try and document/educate every JS developer who finds js-ipfs.

We’ve already done far more work to stabilize js-ipfs and ensure there aren’t breaking changes between these releases than the average package on npm, it seems silly that we wouldn’t just adjust the versioning along with it in order to gain more adoption given that we’re putting in all of this effort to avoid breaking changes anyway.

[olizilla]

I agree with @mikeal, but we got here as there was a desire to make 1.0 mean something about defining an API that we want to commit to. It feels like we did that a long time ago, but still #1563 (comment)

Otherwise I am fine with patches for bug fixes, minor for everything else. Seems like it 'd be 0.40.0 then 0.40.1 when we spot the terrible regression, then 0.41.0 and 0.41.1 ~6 weeks later which seems nice and predictable

[momack2]

@mikeal - I don't think this is the right place to have that discussion. Feel free to start a separate issue, but I don't want to block merging this release process description on changing a very embedded IPFS standard - aka that 1.0 means interface reliability / forwards compatibility. Changing that current practice is a separate discussion.

I'm supportive of consistency between the js and go - aka patches should be for bug fixes or very scoped improvements - and minor should be for all new features (regardless of compatibility) such that they have testing.

[alanshaw]

I agree with @momack2, we should have that discussion elsewhere as it's not the question on the table right now and I don't want to further expand the scope of this PR.

It sounds as if there's at least agreement that we should switch to MINOR for all features (and breaks) and PATCH exclusively for bug fixes which I'm happy to do right now and would be consistent with go-ipfs so lets do that! 🚢🚢🚢

FWIW I have a strong desire to use the major version number and I dislike that 1.0 is this big milestone for stable, production ready, "finished" to a lot of people. We lose a lot of power of semver by not using the major version number and as @mikeal pointed out many people (and machines) are still going to view anything pre-1.0 as unstable and likely to change and break, whatever convention we use for pre-1.0 versioning.

[mikeal]

sorry, wasn’t intending to block the merge, that’s why it’s just a comment and a not a full review. the change being discussed is a positive move in the right direction, i don’t see any need to block it.

[alanshaw]

No worries - it is a necessary point to make, I'm glad someone bought it up 🙂

Lets open an issue and pick up where we left off.

[alanshaw]

Does this make sense? I've been doing this already for non-feature complete pre-releases but I realised I've not openly communicated this.

[alanshaw]

Again, this is a noop for js-ipfs right now but with the addition of /refs and now GC we're one step closer to being able to be our own preload node.

[jacobheun]

This looks good to me, just some minor suggestions.

[jacobheun]

I think this is reasonable with a 6 week release cycle.

[hugomrdias]

LGTM

[daviddias]

❤️❤️❤️❤️ This is really great!

[vasco-santos]

🎉

[lidel]

LGTM (with small URL fixes below).

[lidel]

I wonder if we should include ipfs-postmsg-proxy as a separate thing. Thoughts?

[achingbrain]

This all sounds good. My feeling is that six weeks is a really long time for a release - we should be able to automate pretty much everything apart from the community testing/feedback bit.

For example, we should publish an RC to npm every time the head of the release branch changes (using GH actions? I don't know - @olizilla has done a bunch of stuff with automating publishing with secrets). I'm not above setting up a Jenkins box under my desk to do this if necessary.

For testing dependent projects, greenkeeper already PRs new versions against dependents - it's not massively visible though, maybe we need a dashboard of which PRs are failing/unmerged. We could also split our examples into separate repos to do the same thing, or add a test suites to for them to js-IPFS itself.

@alanshaw points out his FileCoin tool for grepping contributors out of the git logs of all the various deps that change in a release, great, same thing for IPFS please. We could then generate template blog posts etc (to be fleshed out by a human, obvs, but a bullet-point list of things to mention and people to thank would speed things along).

I think all of this fits within the framework proposed above, it's just taking as much manual work out as possible - it would be great to bring that 6 week window down over time.

[achingbrain]

FWIW we're going to trial this in the next js-IPFS release and may make "improvements" to the process if it doesn't work in practice. Monday 9th September is day 0, drawbridge up, feature freeze, etc.

From a practical perspective this means creating a release branch with npm-shrinkwrap.json and yarn.lock files, all subsequently merged PRs will go into master so development can continue, but RCs will be published from the release branch and bug fixes will be cherry-picked between master and the release branch as necessary.