|
| 1 | +<!--- |
| 2 | +Copyright BigchainDB GmbH and BigchainDB contributors |
| 3 | +SPDX-License-Identifier: (Apache-2.0 AND CC-BY-4.0) |
| 4 | +Code is Apache-2.0 and docs are CC-BY-4.0 |
| 5 | +---> |
| 6 | + |
| 7 | +# Our Release Process |
| 8 | + |
| 9 | +## Notes |
| 10 | + |
| 11 | +BigchainDB follows |
| 12 | +[the Python form of Semantic Versioning](https://packaging.python.org/tutorials/distributing-packages/#choosing-a-versioning-scheme) |
| 13 | +(i.e. MAJOR.MINOR.PATCH), |
| 14 | +which is almost identical |
| 15 | +to [regular semantic versioning](http://semver.org/), but there's no hyphen, e.g. |
| 16 | + |
| 17 | +- `0.9.0` for a typical final release |
| 18 | +- `4.5.2a1` not `4.5.2-a1` for the first Alpha release |
| 19 | +- `3.4.5rc2` not `3.4.5-rc2` for Release Candidate 2 |
| 20 | + |
| 21 | +**Note:** For Git tags (which are used to identify releases on GitHub), we append a `v` in front. |
| 22 | + |
| 23 | +We follow [BEP-1](https://github.com/bigchaindb/BEPs/tree/master/1), which is our variant of C4, the Collective Code Construction Contract, so a release is just a [tagged commit](https://git-scm.com/book/en/v2/Git-Basics-Tagging) on the `master` branch, i.e. a label for a particular Git commit. |
| 24 | + |
| 25 | +## Steps |
| 26 | + |
| 27 | +1. Make sure you have a recent version of node and npm. |
| 28 | +1. `npm install` |
| 29 | +1. Update all npm package dependencies, where possible. You might have to freeze some versions. Run all tests locally (`npm run test`) and make sure they pass. Make a pull request (to be merged into the `master` branch) and make sure all tests are passing there (in Travis). Merge the pull request. |
| 30 | +1. Make sure your local `master` branch is in sync with GitHub: `git checkout master` and `git pull` |
| 31 | +1. Do a test build: |
| 32 | + |
| 33 | + `npm run build` |
| 34 | + |
| 35 | + If that fails, then get it working. |
| 36 | +1. We use the [release-it](https://www.npmjs.com/package/release-it) package (from npm) to automate most of the release. Make sure you have a recent version. |
| 37 | +1. Login to npm using your npm credentials, so you can publish a new [bigchaindb-driver](https://www.npmjs.com/package/bigchaindb-driver) package there. (The npm account must haver permission to do so). |
| 38 | + |
| 39 | + `npm login` |
| 40 | + |
| 41 | +1. release-it needs a Github personal access token so it can interact with GitHub on your behalf. To get one, go to: |
| 42 | + |
| 43 | + [https://github.com/settings/tokens](https://github.com/settings/tokens) |
| 44 | + |
| 45 | + and then make that token available as an environment variable, e.g. |
| 46 | + |
| 47 | + `export GITHUB_TOKEN="f941e0..."` |
| 48 | + |
| 49 | +1. Do the release: |
| 50 | + |
| 51 | + - For a patch release, do `npm run release` |
| 52 | + - For a minor release, do `npm run release-minor` |
| 53 | + - For a major release, do `npm run release-major` |
| 54 | + |
| 55 | + If your npm account is using two-factor authentication, |
| 56 | + you will have to append a one-time password (OTP) like `--npm.otp=123456`. |
| 57 | + The above command will automatically do a bunch of things: |
| 58 | + |
| 59 | + - bump the project version in `package.json`, then git commit and git push it. |
| 60 | + - create a new Git tag of the form `v{verson}`, e.g. `v1.2.3` |
| 61 | + - create a new [GitHub release](https://github.com/bigchaindb/js-bigchaindb-driver/releases). |
| 62 | + - publish a new npm release |
| 63 | + |
| 64 | + To see all the arguments passed to `release-it`, search for "release" in [package.json](package.json). The arguments are documented in the [release-it GitHub repo](https://github.com/release-it/release-it). |
| 65 | + |
| 66 | +1. Make sure everything worked as expected. |
| 67 | + |
| 68 | + - Was the version number bumped properly in [package.json](package.json)? |
| 69 | + - Was a new Git tag created? See the [list of tags](https://github.com/bigchaindb/js-bigchaindb-driver/tags). |
| 70 | + - Was a new GitHub release created? See the [list of releases](https://github.com/bigchaindb/js-bigchaindb-driver/releases). |
| 71 | + - Was a new npm package published on npm? [Check on npmjs.com](https://www.npmjs.com/package/bigchaindb-driver). |
| 72 | + |
| 73 | +1. You can edit the description of the GitHub release to add or remove details. |
| 74 | + |
| 75 | +If the docs were updated since the last release, [login to readthedocs.org](https://readthedocs.org/accounts/login/) and go to the **BigchainDB JavaScript Driver** project, then: |
| 76 | + |
| 77 | +1. Click on "Builds", select "latest" from the drop-down menu, then click the "Build Version:" button. |
| 78 | +1. Wait for the build of "latest" to finish. This can take a few minutes. |
| 79 | +1. Go to Admin --> Advanced Settings |
| 80 | + and make sure that "Default branch:" (i.e. what "latest" points to) |
| 81 | + is set to the new release's tag, e.g. `v0.9.1`. |
| 82 | + (It won't be an option if you didn't wait for the build of "latest" to finish.) |
| 83 | + Then scroll to the bottom and click "Save". |
| 84 | +1. Go to Admin --> Versions |
| 85 | + and under **Choose Active Versions**, do these things: |
| 86 | + |
| 87 | + 1. Make sure that the new version's tag is "Active" and "Public" |
| 88 | + 1. Make sure the **stable** branch is _not_ active. |
| 89 | + 1. Scroll to the bottom of the page and click "Save". |
| 90 | + |
| 91 | +Congratulations, you have released a new version of the BigchainDB JavaScript Driver! |
0 commit comments