refactor: improvements to the release process (#2408)

License: MIT
Signed-off-by: Alan Shaw <[email protected]>

Author: Alan Shaw

RELEASE.md

@@ -0,0 +1,29 @@
+# Early Testers Programme
+
+## What is it?
+
+The early testers programme allows groups using js-ipfs in production to self-volunteer to help test js-ipfs release candidates to ensure that no regressions that might affect production systems make it into the final release. While we invite the _entire_ community to help test releases, members of the early testers program are expected to participate directly and actively in every release.
+
+## What are the expectations?
+
+Members of the early tester program are expected to work closely with us to:
+
+* Provide high quality, actionable feedback.
+* Work directly with us to debug regressions in the release.
+* Help ensure a rock-solid, timely release.
+
+We will ask early testers to participate at two points in the process:
+
+* When js-ipfs enters the second release stage, early testers will be asked to test js-ipfs on non-production infrastructure. This may involve things like:
+  - Running integration tests against the release candidate.
+  - Running simulations/benchmarks on the release candidate.
+  - Manually testing the release candidate to check for regressions.
+* When js-ipfs enters the third release stage (soft release), early testers will be asked to partially deploy the release candidate to production infrastructure. Release candidates at this stage are expected to be identical to the final release. However, this stage allows the js-ipfs team to fix any last-minute regressions without cutting an entirely new release.
+
+## Who has signed up?
+
+No early testers volunteers yet!
+
+## How to sign up?
+
+Simply submit a PR to this document by adding your project name and contact.

doc/EARLY_TESTERS.md

@@ -0,0 +1,126 @@
+# Release 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>
+
+# 🚢 Estimated shipping date
+
+<Date this release will ship on if everything goes to plan (week beginning...)>
+
+# 🔦 Highlights
+
+<Top highlights for this release>
+
+# 🏗 API Changes
+
+<Any API changes breaking or otherwise that people should know of>
+
+# ✅ Release Checklist
+
+- [ ] **Stage 0 - Automated Testing**
+  - [ ] Feature freeze. If any "non-trivial" changes (see the footnotes of [doc/releases.md](https://github.com/ipfs/js-ipfs/tree/master/doc/releases.md) for a definition) get added to the release, uncheck all the checkboxes and return to this stage.
+  - [ ] Automated Testing (already tested in CI) - Ensure that all tests are passing, this includes:
+    - [ ] unit/functional/integration/e2e
+    - [ ] interop
+    - [ ] sharness
+- [ ] **Stage 1 - Internal Testing**
+  - [ ] Publish a release candidate to npm
+    ```sh
+    # Clean out node_modules and re-install dependencies
+    # (Ensures you have the latest versions for the browser build)
+    rm -rf node_modules package-lock.json
+    npm install
+
+    # Minor prerelease (e.g. 0.33.1 -> 0.34.0-rc.0)
+    npx aegir release --type preminor --preid rc --dist-tag next
+
+    # Increment prerelease (e.g. 0.34.0-rc.0 -> 0.34.0-rc.1)
+    npx aegir release --type prerelease --preid rc --dist-tag next
+    ```
+  - Network Testing:
+    - test lab things - TBD
+  - Infrastructure Testing:
+    - TBD
+  - [ ] IPFS Application Testing - Run the tests of the following applications:
+    - [ ] [webui](https://github.com/ipfs-shipyard/ipfs-webui)
+    - [ ] [ipfs-desktop](https://github.com/ipfs-shipyard/ipfs-desktop)
+    - [ ] [ipfs-companion](https://github.com/ipfs-shipyard/ipfs-companion)
+    - [ ] [npm-on-ipfs](https://github.com/ipfs-shipyard/npm-on-ipfs)
+    - [ ] [ipfs-pubsub-room](https://github.com/ipfs-shipyard/ipfs-pubsub-room)
+    - [ ] [peer-base](https://github.com/peer-base/peer-base)
+    - [ ] [service-worker-gateway](https://github.com/ipfs-shipyard/service-worker-gateway)
+- [ ] **Stage 2 - Community Dev Testing**
+  - [ ] Reach out to the IPFS _early testers_ listed in [doc/EARLY_TESTERS.md](https://github.com/ipfs/js-ipfs/tree/master/doc/EARLY_TESTERS.md) for testing this release (check when no more problems have been reported). If you'd like to be added to this list, please file a PR.
+  - [ ] Reach out on IRC for additional early testers.
+  - [ ] Run tests available in the following repos with the latest RC:
+    - [ ] [ipfs-log](https://github.com/orbitdb/ipfs-log)
+    - [ ] [orbit-db](https://github.com/orbitdb/orbit-db)
+- [ ] **Stage 3 - Community Prod Testing**
+  - [ ] Documentation
+    - [ ] Ensure that [README.md](https://github.com/ipfs/js-ipfs/tree/master/README.md) is up to date
+    - [ ] Ensure that all the examples run without problems:
+      - [ ] https://github.com/ipfs/js-ipfs/tree/master/examples/browser-add-readable-stream
+      - [ ] https://github.com/ipfs/js-ipfs/tree/master/examples/browser-browserify
+      - [ ] https://github.com/ipfs/js-ipfs/tree/master/examples/browser-mfs
+      - [ ] https://github.com/ipfs/js-ipfs/tree/master/examples/browser-parceljs
+      - [ ] https://github.com/ipfs/js-ipfs/tree/master/examples/browser-readablestream
+      - [ ] https://github.com/ipfs/js-ipfs/tree/master/examples/browser-script-tag
+      - [ ] https://github.com/ipfs/js-ipfs/tree/master/examples/browser-video-streaming
+      - [ ] https://github.com/ipfs/js-ipfs/tree/master/examples/browser-vue
+      - [ ] https://github.com/ipfs/js-ipfs/tree/master/examples/browser-webpack
+      - [ ] https://github.com/ipfs/js-ipfs/tree/master/examples/circuit-relaying
+      - [ ] https://github.com/ipfs/js-ipfs/tree/master/examples/custom-ipfs-repo
+      - [ ] https://github.com/ipfs/js-ipfs/tree/master/examples/custom-libp2p
+      - [ ] https://github.com/ipfs/js-ipfs/tree/master/examples/exchange-files-in-browser
+      - [ ] https://github.com/ipfs/js-ipfs/tree/master/examples/explore-ethereum-blockchain
+      - [ ] https://github.com/ipfs/js-ipfs/tree/master/examples/ipfs-101
+      - [ ] https://github.com/ipfs/js-ipfs/tree/master/examples/run-in-electron
+      - [ ] https://github.com/ipfs/js-ipfs/tree/master/examples/running-multiple-nodes
+      - [ ] https://github.com/ipfs/js-ipfs/tree/master/examples/traverse-ipld-graphs
+    - [ ] Update [js.ipfs.io](https://js.ipfs.io) examples to use the latest js-ipfs
+  - [ ] Invite the IPFS [_early testers_](https://github.com/ipfs/js-ipfs/tree/master/doc/EARLY_TESTERS.md) to deploy the release to part of their production infrastructure.
+  - [ ] Invite the wider community (link to the release issue):
+    - [ ] [discuss.ipfs.io](https://discuss.ipfs.io/c/announcements)
+    - [ ] Twitter
+    - [ ] IRC
+- [ ] **Stage 4 - Release**
+  - [ ] Take a snapshot of everyone that has contributed to this release (including its direct dependencies in IPFS, libp2p, IPLD and multiformats) using [this script](https://gist.github.com/alanshaw/5a2d9465c5a05b201d949551bdb1fcc3).
+  - [ ] Publish to npm:
+    ```sh
+    # Clean out node_modules and re-install dependencies
+    # (Ensures you have the latest versions for the browser build)
+    rm -rf node_modules package-lock.json
+    npm install
+
+    # lint, build, test, tag, publish
+    npm run release-minor
+    ```
+  - [ ] Publish a blog post to [github.com/ipfs/blog](https://github.com/ipfs/blog) (at minimum, a c&p of this release issue with all the highlights, API changes and thank yous)
+  - [ ] Broadcasting (link to blog post)
+    - [ ] Twitter
+    - [ ] IRC
+    - [ ] [Reddit](https://reddit.com/r/ipfs)
+    - [ ] [discuss.ipfs.io](https://discuss.ipfs.io/c/announcements)
+    - [ ] Announce it on the [IPFS Users Mailing List](https://groups.google.com/forum/#!forum/ipfs-users)
+  - [ ] Copy release notes to the [GitHub Release description](https://github.com/ipfs/js-ipfs/releases)
+
+# ❤️ Huge thank you to everyone that made this release possible
+
+<Generated contributor list>
+
+# 🙌🏽 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 [js-ipfs repo](https://github.com/ipfs/js-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
+- 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 https://discuss.ipfs.io/ and help users finding their answers.
+- Join the [🚀 IPFS Core Implementations Weekly Sync 🛰](https://github.com/ipfs/team-mgmt/issues/992) and be part of the action!
+
+# ⁉️ 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](https://discuss.ipfs.io). We are also available at the `#ipfs` channel on Freenode.

doc/RELEASE_ISSUE_TEMPLATE.md

@@ -0,0 +1,120 @@
+# Releases
+
+## Table of Contents
+
+- [Release Philosophy](#release-philosophy)
+- [Release Flow](#release-flow)
+  - [Stage 0 - Automated Testing](#stage-0---automated-testing)
+  - [Stage 1 - Internal Testing](#stage-1---internal-testing)
+  - [Stage 2 - Community Dev Testing](#stage-2---community-dev-testing)
+  - [Stage 3 - Community Prod Testing](#stage-3---community-prod-testing)
+  - [Stage 4 - Release](#stage-4---release)
+- [Release Cycle](#release-cycle)
+  - [Patch Releases](#patch-releases)
+- [Performing a Release](#performing-a-release)
+- [Release Version Numbers](#release-version-numbers)
+  - [Pre-Releases and Release Candidates](#pre-releases-and-release-candidates)
+
+## Release Philosophy
+
+js-ipfs aims to have release every six weeks, two releases per quarter. During these 6 week releases, we go through 4 different stages that gives us the opportunity to test the new version against our test environments (unit, interop, integration), QA in our current production environment, IPFS apps (e.g. Desktop and WebUI) and with our community and _early testers_<sup>[1]</sup> that have IPFS running in production.
+
+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
+
+js-ipfs releases come in 5 stages designed to gradually roll out changes and reduce the impact of any regressions that may have been introduced. If we need to merge non-trivial<sup>[2]</sup> changes during the process, we start over at stage 0.
+
+![js-ipfs release flow cartoon](https://ipfs.io/ipfs/QmU5pwcGh38DqzLy3rK8GAHuWm2kK87oGqDAtqZYWhxjab)
+
+### Stage 0 - Automated Testing
+
+At this stage, we expect _all_ automated tests (unit, functional, integration, interop, testlab, performance, etc.) to pass.
+
+### Stage 1 - Internal Testing
+
+At this stage, we'll:
+
+1. Start a partial-rollout to our own infrastructure.
+2. Test against applications in the [ipfs](https://github.com/ipfs/) and [ipfs-shipyard](https://github.com/ipfs-shipyard/) organisations and a selection of other hand picked projects.
+
+**Goals:**
+
+1. Make sure we haven't introduced any obvious regressions.
+2. Test the release in an environment we can monitor and easily roll back (i.e. our own infra).
+
+### Stage 2 - Community Dev Testing
+
+At this stage, we'll announce the impending release to the community and ask for pre-release testers.
+
+**Goal:**
+
+Test the release in as many non-production environments as possible. This is relatively low-risk but gives us a _breadth_ of testing internal testing can't.
+
+### Stage 3 - Community Prod Testing
+
+At this stage, we consider the release to be "production ready" and will ask the community and our early testers to (partially) deploy the release to their production infrastructure.
+
+**Goals:**
+
+1. Test the release in some production environments with heavy workloads.
+2. Partially roll-out an upgrade to see how it affects the network.
+3. Retain the ability to ship last-minute fixes before the final release.
+
+### Stage 4 - Release
+
+At this stage, the release is "battle hardened" and ready for wide deployment. A new version is published to npm, announcements are made and a blog post is published to [blog.ipfs.io](https://blog.ipfs.io).
+
+## Release Cycle
+
+A full release process should take about 3 weeks, a week per stage 1-3. We will start a new process every 6 weeks, regardless of when the previous release landed unless it's still ongoing.
+
+### Patch Releases
+
+If we encounter a serious bug in the stable latest release, we will create a patch release based on this release. For now, bug fixes will _not_ be backported to previous releases.
+
+Patch releases will usually follow a compressed release cycle and should take 2-3 days. In a patch release:
+
+1. Automated and internal testing (stage 0 and 1) will be compressed into a few hours - ideally less than a day.
+2. Stage 2 will be skipped.
+3. Community production testing will be shortened to 1-2 days of opt-in testing in production (early testers can choose to pass).
+
+Some patch releases, especially ones fixing one or more complex bugs, may undergo the full release process.
+
+## Performing a Release
+
+The release is managed by the "Lead Maintainer" for js-ipfs. It starts with the opening of an issue containing the content available on the [RELEASE_ISSUE_TEMPLATE](./RELEASE_ISSUE_TEMPLATE.md) not more than **48 hours** after the previous release.
+
+This issue is pinned and labeled ["release"](https://github.com/ipfs/js-ipfs/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+label%3Arelease). When the cycle is due to begin the 5 stages will be followed until the release is done.
+
+## Release Version Numbers
+
+js-ipfs is currently pre-1.0. In semver terms this means [anything may change at any time](https://semver.org/#spec-item-4).
+
+However, pre-1.0 js-ipfs reserves MINOR version increments for BREAKING CHANGES _and_ feature additions and PATCH version increments for bug fixes.
+
+Post `1.x.x` (future), MAJOR version number increments will contain BREAKING CHANGES, MINOR version increments will be reserved for backwards compatible new features and PATCH version increments 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.
+
+### Pre-Releases and Release Candidates
+
+Prior to or during the early stages of a release cycle, js-ipfs may release a pre-release version for users who want to try out the "bleeding edge". This typically happens when a new major feature or breaking change lands in master. When this happens is entirely at the discretion of the Lead Maintainer.
+
+Pre-release version numbers take the form `x.y.z-pre.n`.
+
+Where `x`, `y`, and `z` are the usual MAJOR, MINOR and PATCH version numbers and `n` (starting at 0) increments by 1 for every pre-release version that is released.
+
+Following any pre-releases, at least one release candidate will be published during stage 1/2.
+
+Release candidate version numbers take the form `x.y.z-rc.n`.
+
+Where `x`, `y`, and `z` are the usual MAJOR, MINOR and PATCH version numbers and `n` (starting at 0) increments by 1 for every release candidate that is released.
+
+---
+
+- <sup>**[1]**</sup> - _early testers_ is an IPFS programme in which members of the community can self-volunteer to help test `js-ipfs` Release Candidates. You find more info about it at [EARLY_TESTERS.md](./EARLY_TESTERS.md)
+- <sup>**[2]**</sup> - A non-trivial change is any change that could potentially introduce an issue that could not categorically be caught by automated testing. This is up to the discretion of the Lead Maintainer but the assumption is that every change is non-trivial unless proven otherwise.