Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Revamp go-ipfs Release Flow #6482

Merged
merged 29 commits into from
Jul 12, 2019
Merged
Changes from 2 commits
Commits
Show all changes
29 commits
Select commit Hold shift + click to select a range
6751f71
docs: update Release Flow
daviddias Jul 3, 2019
a066a70
Update docs/releases.md
daviddias Jul 3, 2019
5a98567
apply review
daviddias Jul 4, 2019
1196554
create stub for EARLY TESTERS
daviddias Jul 4, 2019
bb096ad
Update releases.md
daviddias Jul 4, 2019
c76cc59
docs: releases.md spelling
Stebalien Jul 8, 2019
23df118
add more testers to EARLY_TESTERS along with contact info
Stebalien Jul 8, 2019
b786abe
docs: remove early testers from docs/releases.md so it doesn't get ou…
Stebalien Jul 8, 2019
9bb15f2
releases: switch to a soft release model
Stebalien Jul 11, 2019
72b9c4a
Update and rename RELEASE_TEMPLATE.md to RELEASE_ISSUE_TEMPLATE.md
daviddias Jul 12, 2019
a32d5e9
Update releases.md
daviddias Jul 12, 2019
63f6699
Update RELEASE_ISSUE_TEMPLATE.md
daviddias Jul 12, 2019
4fb38a7
Merge pull request #6500 from ipfs/release-flow-steb2
daviddias Jul 12, 2019
b31cbb0
Update docs/RELEASE_ISSUE_TEMPLATE.md
daviddias Jul 12, 2019
dec2ef9
Update docs/RELEASE_ISSUE_TEMPLATE.md
daviddias Jul 12, 2019
fa7c3a8
Update docs/RELEASE_ISSUE_TEMPLATE.md
daviddias Jul 12, 2019
ac89a1f
Update docs/RELEASE_ISSUE_TEMPLATE.md
daviddias Jul 12, 2019
4f846ce
Update docs/RELEASE_ISSUE_TEMPLATE.md
daviddias Jul 12, 2019
31f28a0
docs: visually separate per-stage checklist from overall checklist
Stebalien Jul 12, 2019
6895d8c
docs: grammar
Stebalien Jul 12, 2019
15fcea2
Update docs/releases.md
daviddias Jul 12, 2019
a92d07f
Update docs/releases.md
daviddias Jul 12, 2019
e979f6e
doc: define non-trivial
Stebalien Jul 12, 2019
7a3bfde
docs(RELEASE_ISSUE_TEMPLATE): link all the things
Stebalien Jul 12, 2019
16de302
doc: update checklist with more precise instructions
Stebalien Jul 12, 2019
c4fa1ba
Update RELEASE_ISSUE_TEMPLATE.md
djdv Jul 12, 2019
5aa32db
doc: add github release to the release checklist
Stebalien Jul 12, 2019
6b5d521
doc: add dist.ipfs.io instructions to the release checklist
Stebalien Jul 12, 2019
206b039
doc: flesh out early testers program
Stebalien Jul 12, 2019
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
182 changes: 150 additions & 32 deletions docs/releases.md
Original file line number Diff line number Diff line change
@@ -1,39 +1,157 @@
# go-ipfs releases
# `go-ipfs` Release Flow

## Release Schedule
go-ipfs is on a six week release schedule. Following a release, there will be
five weeks for code of any type (features, bugfixes, etc) to be added. After
the five weeks is up, a release candidate is tagged and only important bugfixes
will be allowed up to release day.
## Table of Contents

## Release Candidate Checklist
- [ ] CHANGELOG.md has been updated
- use `./bin/mkreleaselog` to generate a nice starter list
- [Release Philosophy](#release-philosophy)
- [Release Flow](#release-flow)
- [Performing a Release](#performing-a-release)
- [Release Version Numbers (aka semver)](#release-version-numbers-aka-semver)

## Release Philosophy

`go-ipfs` aims to have release every six weeks, two releases per quarter. During these 6 week releases, we go through 4 different stages of Release Candidates (RC) that gives us the opportunity to test the new version against our test envinronments, production envinronments, IPFS apps (e.g. Desktop and WebUI) and with our close partners that have IPFS running in Production, by leveraging their own test infrastructure.
daviddias marked this conversation as resolved.
Show resolved Hide resolved

We might expand the six week release schedule in case of:
- No new updates to be added
- In case of a large community event that takes the core team availability away (e.g. IPFS Conf, Dev Meetings, IPFS Camp, etc)

## Release Flow

`go-ipfs` releases come in 4 stages:

- **Release Stage 1 - Internal testing** - Test the Release against our testing infrastructure, including interoperability, integration, test lab, multiple runtimes and the apps we've built (WebUI, Desktop, NPM on IPFS, HTTP Client Libraries). The intent is to make this stage fully automated (and somewhat is already), until then, we manually check a list and ensure that all tests have been run
- **Release Stage 2 - Invite IPFS partners to test** - Reach out to our partners (i.e. projects that have volunteered to support `go-ipfs` by using their own test infrastructure and tell us the results)
daviddias marked this conversation as resolved.
Show resolved Hide resolved
- **Release Stage 3 - Announce to the broader community** - Communicate to the community that a new Release Candidate is ready and that everyone is welcome to test it with us
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Any real reason not to combine stages 2 and 3? Really, we usually ask the broader community (stage 3) first because they tend not to be using IPFS for mission critical operations. That is:

  1. Advanced/eager users tend to find "shallow" bugs: api breakage, bad documentation, etc.
  2. Partners tend to find deep bugs: performance regressions, rare crashes, etc.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

My rationale for this separation was based on my assumption that we are very limited in capacity to deal with incoming bug reports.

I expect that our early testers are more knowledgeable and therefore, more capable of debugging themselves part of the problem or at least providing more useful information, which will save us a ton of time and cover a ton of bugs.

In contrast, I expect that the broad community to be able to also pick on bugs but provide less useful information. By doing early testers first, we save some time from debugging less documented/debugged bugs (which would overlap with the ones that our early testers will report).

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That said, I'm not holding any strong feelings towards the flow. Happy to take in the wisdom of the maintainers and iterate on it :)

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What about:

  • Stage 2 - Announce a preliminary RC on IRC and invite the community to run sanity checks.
  • Stage 3 - Pull in partners.
  • Stage 4 - Announce the RC on twitter etc? I wonder if there's some way to allow, e.g., ipfs-desktop users to opt into this release.

I guess I mostly just want a chance to test it with lower stakes than people relying on IPFS in production systems.

My rationale for this separation was based on my assumption that we are very limited in capacity to deal with incoming bug reports.

Most of the bug reports we get from announcements on IRC are actually pretty good. They also tend to be pretty straight forward to diagnose as they aren't subtle performance issues.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

lower stakes than people relying on IPFS in production systems.

We should not advise folks to run RC in production, rather just invite them to test on their test infra and QA if they have it built.

Most of the bug reports we get from announcements on IRC are actually pretty good. They also tend to be pretty straight forward to diagnose as they aren't subtle performance issues.

This is good info to know. If you feel confident on merging Stage 2 and 3, then let's do it. Just confirm and I'll update it

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's sounds weird that certain releases are meant for partners. It sounds like giving early access to features even though it means "try it out". It should be very clear that anyone can try it out. I can also imagine that different partners (and users) may choose to test ipfs pre-releasees at different stages depending on circumstances.

Note that it is also weird that we give some partners a half-baked release to test. Either they test it by deploying it to their users, in which case they should not be given a half-baked release that can break their apps (even if they volunteer), or they have they're own testing environments, in which case they could directly master or a release branch continuously without waiting for a specific release stage.

Otherwise said:

  • Sounds good to have alpha/beta/rcs (we should have a release branch that includes all features in the release and only updates with bugfixes). We should be able to skip certain checkpoints sometimes (like hotfixes to specific issues).
  • Document what the level of maturity is after each checkpoint, so that everyone can test and try it out (partner or not).
  • Create a known and consistent venue to gather feedback on each release (i.e. an issue) and include information from our own testing in it.
  • Let people choose when they test based on their availability, feedback on the current state of the release and issues with the previous release.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We absolutely must not encourage partners to run a RC in production that can potentially harm their service and hurt their users. What we hope is for partners to use their own Beta channels, Testing Infrastructure and potentially QA setup to let us know if the new release passes the tests.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We absolutely must not encourage partners to run a RC in production that can potentially harm their service and hurt their users.

Any release we make can potentially break something. This is an inviolate rule of software and we must not lie to ourselves about this. The goal here is to minimize the impact by deploying in stages, not to avoid all harm.

We definitely shouldn't ask our partners to run RCs that haven't been tested but we should absolutely ask them to run an RC that we believe to be "ready for release", to reduce the impact of any bugs they may encounter. That way they can roll back, we can fix the issue, and then move on with the release cycle without waiting for another release.

What we hope is for partners to use their own Beta channels, Testing Infrastructure and potentially QA setup to let us know if the new release passes the tests.

This would be awesome but it's asking a lot from our partners and isn't currently the weakest part of our release process.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You know, we probably can just call these alpha, beta, etc. That should make this easier to explain to users:

  • Dev - Bleeding Edge.
  • Alpha - Feature Freeze.
  • Beta - Tested but may still be buggy.
  • RC1 - Release quality, small rollout.
  • RC2 - Release quality, larger rollout.
  • Release - Full rollout.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

See: #6496

- **Release Stage 4 - Complete the Release** - Finalize the release, start the next release.

The Release Stages are not linked to Release Candidate numbers, in fact, there can be multiple release candidate per stages as we catch bugs and improve the release itself.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Are we going to be making this clear via some form of numbering of the rc, i.e. v0.4.22-rc-1-3 => Stage 1, iteration 3?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The plan is just to use one number. The RC- signals that there has been a new one published

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

See my comment on alpha, beta, etc. above.


<p align="center">
<a href="https://ipfs.io">
<img src="https://gateway.ipfs.io/ipfs/QmaFtLxoCAm5vFQ9AftKkhJwSAdDdF1jzV9DfzW6gbXqFL/Paper.Sketches.23.png" width="450" />
</a>
</p>

## Performing a Release

The first step is for the `Lead Maintainer` for `go-ipfs` to open an issue with Title `go-ipfs <version> Release` and a c&p of the following template:

```
> <short tl;dr; of the release>

# 🗺 What's left for release

<List of items with PRs and/or Issues to be considered for this release>

# 🔦 Highlights

<List of items with PRs and/or Issues to be considered for this release>
daviddias marked this conversation as resolved.
Show resolved Hide resolved

# 🏗 API Changes

<List of API changes, if any>
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The 🔦 Highlights and 🏗 API Changes could potentially be replaced by the Changelog. That said, there is still value on highlighting some of the changes, the ones that we want users to know about first (or the ones that we want to ensure that users see, in case they don't have time to read the entire changelog).

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Or, more generally, breaking changes/notices.


# ✅ Release Checklist

For each RC published in each stage:
- [ ] version string in `version.go` has been updated
- [ ] tag commit with vX.Y.Z-rcN

## Pre-Release Checklist
- [ ] before release, tag 'release candidate' for users to test against
- if bugs are found/fixed, do another release candidate
- [ ] all tests pass (no exceptions)
- [ ] run interop tests https://github.com/ipfs/interop#test-with-a-non-yet-released-version-of-go-ipfs
- [ ] webui works (for most definitions of 'works') - Test the multiple pages and verify that no visible errors are shown.
### Release Stage 1 - Internal testing
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Note: as noted on Release Flow, this whole stage can potentially be automated. Until it is, let's have the items as a check list so that we don't forget any :)


When Release Stage 1, there is a features freeze for the release branch.

- [ ] CHANGELOG.md has been updated
- use `./bin/mkreleaselog` to generate a nice starter list
- [ ] version string in `repo/version.go` has been updated
- [ ] tag commit with vX.Y.Z
- [ ] update release branch to point to release commit (`git merge vX.Y.Z`).
- [ ] publish dist.ipfs.io
- [ ] publish next version to https://github.com/ipfs/npm-go-ipfs

## Post-Release
- [ ] Bump version string in `repo/version.go` to `vX.Y.Z-dev`
- [ ] Upload the final release to the github releases page: https://github.com/ipfs/go-ipfs/releases
- Communication
- [ ] Create the release issue
- [ ] Announcements (both pre-release and post-release)
- [ ] Twitter
- [ ] IRC
- [ ] Reddit
- [ ] Blog post (at minimum, paste the changelog. optionally add context and thank contributors.)
- [ ] Update HTTP-API Documentation on the Website using https://github.com/ipfs/http-api-docs
- [ ] Automated Testing - Ensure that all tests are passing, this includes:
- [ ] unit
- [ ] sharness
- [ ] [interop](https://github.com/ipfs/interop#test-with-a-non-yet-released-version-of-go-ipfs)
- [ ] Network Testing:
- [ ] test lab things
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We don't have this yet.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@bigs isn't there a thing?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It is a thing but not yet for IPFS just yet.

- [ ] Infrastructure Testing:
- [ ] Deploy new version to a subset of Bootstrappers
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can we even do this yet? cc @ipfs/wg-infrastructure.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

- [ ] Deploy new version to a subset of Gateways
- [ ] Deploy new version to a subset of Preload nodes
- [ ] Collect metrics every day. Work with the Infrastructure team to learn of any hiccup
- [ ] IPFS HTTP Client Libraries Testing:
- [ ] [JS](http://github.com/ipfs/js-ipfs-http-client)
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These are built into the interop tests.

- [ ] [Go](https://github.com/ipfs/go-ipfs-api)
- [ ] IPFS Application Testing - Run the tests of the following applications:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

IPFS Cluster?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We're going to need DRIs for this. Maybe add a line about pinging the relevant maintainers?

- [ ] WebUI
- [ ] IPFS Desktop
- [ ] IPFS Companion
- [ ] NPM on IPFS

### Release Stage 2 - Invite IPFS partners to test

- [ ] Reach out to the following IPFS partners for testing this release (check when no more problems have been reported):
- [ ] Infura
- [ ] Textila
- [ ] Open Bazaar
- [ ] QRI
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's add Pinata and remove Open Bazaar (forked version).

- [ ] Run tests available in the following repos with the latest RC (check when all tests pass):
- [ ] [orbit-db](https://github.com/orbitdb/orbit-db)
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm pretty sure that both of the lists here can be way bigger. We probably should have a "expectations description" before adding more folks

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can we test this against go-ipfs? I thought it embedded a js-ipfs node.

Copy link
Member Author

@daviddias daviddias Jul 3, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

AFAIK, it can do both. Will check again.

For the other readers. What @Stebalien meant by this was just referring to orbit-db and not all the other apps.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

(yes, sorry)


PSA: If you are a heavy user of `go-ipfs`, have developed a solid test infrastructure for your application and would love to help us would like to help us test `go-ipfs` release candidates, reach out to go-ipfs-wg@ipfs.io.

### Release Stage 3 - Announce to the broader community

- [ ] Documentation
- [ ] Ensure that CHANGELOG.md is up to date
- [ ] Ensure that README.md is up to date
Copy link
Member

@lidel lidel Jul 8, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I past we had times when parts of docs/config.md and docs/experimental-features.md got out of date. Its the source of truth for many power users. It should be a part of the checklist:

Suggested change
- [ ] Ensure that README.md is up to date
- [ ] Ensure that README.md is up to date
- [ ] Ensure that `docs/config.md` and `docs/experimental-features.md` are up to date

- [ ] Ensure that all the examples we have produced for go-ipfs run without problems
- [ ] Update HTTP-API Documentation on the Website using https://github.com/ipfs/http-api-docs
- [ ] Invite the community through (link to the release issue):
- [ ] [discuss.ipfs.io](https://discuss.ipfs.io/c/announcements)
- [ ] Twitter
daviddias marked this conversation as resolved.
Show resolved Hide resolved

### Release Stage 4 - Complete the Release

- Take a snapshot between of everyone that has contributed to this release (including its subdeps in IPFS, libp2p, IPLD and multiformats) using [`name-your-contributors`](https://www.npmjs.com/package/name-your-contributors). Generate a nice markdown list with [this script](https://gist.github.com/alanshaw/5a2d9465c5a05b201d949551bdb1fcc3). Add it to this issue.
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This gist needs to be updated to point to the go code repos. Thanks to @alanshaw for creating it in the first place.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.


- [ ] Final preparation
- [ ] Verify that version string in `repo/version.go` has been updated
- [ ] tag commit with vX.Y.Z
- [ ] update release branch to point to release commit (`git merge vX.Y.Z`).
- [ ] publish dist.ipfs.io
- [ ] publish next version to https://github.com/ipfs/npm-go-ipfs
- [ ] Publish a Release Blog post (at minimum, a c&p of this release issue with all the highlights, API changes, link to changelog and thank yous)
- [ ] Broadcasting (link to blog post)
- [ ] Twitter
- [ ] IRC
- [ ] Reddit
- [ ] [discuss.ipfs.io](https://discuss.ipfs.io/c/announcements)
- [ ] Announce it on the [IPFS Users mlist](https://groups.google.com/forum/#!forum/ipfs-users)

# ❤️ Huge thank you to everyone that made this release possible

In alphabetical order, here are all the humans that contributed to the release:

- <use script -- listed in Release Stage 4 -- to generate a list of everyone that contributed for this release>

# 🙌🏽 Want to contribute?

Would you like to contribute to the IPFS project and don't know how? Well, there are a few places you can get started:

- Check the issues with the `help wanted` label in the [go-ipfs repo](https://github.com/ipfs/go-ipfs/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22)
- Join an IPFS All Hands, introduce yourself and let us know where you would like to contribute - https://github.com/ipfs/team-mgmt/#weekly-ipfs-all-hands
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe we should start pointing people at IRC/Matrix instead of the All Hands.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Multiple people have reported that showing up on the main channel on IRC with ideas and questions typically results into them falling into oblivion.

If someone is new, it is nice to see that there are humans, that is why the call is important.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fair enough.

- Hack with IPFS and show us what you made! The All Hands call is also the perfect venue for demos, join in and show us what you built
- Join the discussion at http://discuss.ipfs.io/ and help users finding their answers.
- Join the [Go Core Dev Team Weekly Sync](https://github.com/ipfs/team-mgmt/issues/650) and be part of the Sprint action!
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Gone for now.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is there a replacement?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.


# ⁉️ Do you have questions?

The best place to ask your questions about IPFS, how it works and what you can do with it is at [discuss.ipfs.io](http://discuss.ipfs.io). We are also available at the `#ipfs` channel on Freenode.
daviddias marked this conversation as resolved.
Show resolved Hide resolved
```

## Release Version Numbers (aka semver)

Until `go-ipfs` 0.4.X, `go-ipfs` was not using semver to communicate the type of release

Post `go-ipfs` 0.5.X, `go-ipfs` will use semver. This means that patch releases will not contain any breaking changes nor new features. Minor releases might contain breaking changes and always contain some new feature

Post `go-ipfs` 1.X.X (future), `go-ipfs` will use semver. This means that only major releases will contain breaking changes, minors will be reserved for new features and patches for bug fixes.

We do not yet retroactively apply fixes to older releases (no Long Term Support releases for now), which means that we always recommend users to update to the latest, whenever possible.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ho, bummer...

Please consider this in the future for disruptive problems. At Infura we have been stuck with problematic release for months without solution (other than forking): 0.4.19 and 0.4.20 had memory usage problem but we couldn't revert to 0.4.18 due to security reason. This will only become more critical in the future.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In that case, we would have applied the CPU fixes in 0.4.19 to 0.4.18 as a patch. This is just saying that we're not going to release a 0.4.20 and then go back and patch a 0.4.18 release.

TBW
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Anything left here?

daviddias marked this conversation as resolved.
Show resolved Hide resolved