Skip to content

Latest commit

 

History

History
100 lines (84 loc) · 6.12 KB

RELEASE_PROCESS.md

File metadata and controls

100 lines (84 loc) · 6.12 KB
Raw

Our Release Process

Notes

BigchainDB follows the Python form of Semantic Versioning (i.e. MAJOR.MINOR.PATCH), which is almost identical to regular semantic versioning, but there's no hyphen, e.g.

  • 0.9.0 for a typical final release
  • 4.5.2a1 not 4.5.2-a1 for the first Alpha release
  • 3.4.5rc2 not 3.4.5-rc2 for Release Candidate 2

Note 1: For Git tags (which are used to identify releases on GitHub), we append a v in front. For example, the Git tag for version 2.0.0a1 was v2.0.0a1.

Note 2: For Docker image tags (e.g. on Docker Hub), we use longer version names for Alpha, Beta and Release Candidate releases. For example, the Docker image tag for version 2.0.0a2 was 2.0.0-alpha2.

We use 0.9 and 0.9.0 as example version and short-version values below. You should replace those with the correct values for your new version.

We follow BEP-1, which is our variant of C4, the Collective Code Construction Contract, so a release is just a tagged commit on the master branch, i.e. a label for a particular Git commit.

The following steps are what we do to release a new version of BigchainDB Server. The steps to release the Python Driver are similar but not the same.

Steps

  1. Create a pull request where you make the following changes:

    • Update CHANGELOG.md

    • Update all Docker image tags in all Kubernetes YAML files (in the k8s/ directory). For example, in the files:

      • k8s/bigchaindb/bigchaindb-ss.yaml and
      • k8s/dev-setup/bigchaindb.yaml

      find the line of the form image: bigchaindb/bigchaindb:0.8.1 and change the version number to the new version number, e.g. 0.9.0. (This is the Docker image that Kubernetes should pull from Docker Hub.) Keep in mind that this is a Docker image tag so our naming convention is a bit different; see Note 2 in the Notes section above.

    • In bigchaindb/version.py:

      • update __version__ to e.g. 0.9.0 (with no .dev on the end)
      • update __short_version__ to e.g. 0.9 (with no .dev on the end)

    • In the docs about installing BigchainDB (and Tendermint), and in the associated scripts, recommend/install a version of Tendermint that actually works with the soon-to-be-released version of BigchainDB. You can find all such references by doing a search for the previously-recommended version number, such as 0.22.8.

    • In setup.py, maybe update the development status item in the classifiers list. For example, one allowed value is "Development Status :: 5 - Production/Stable". The allowed values are listed at pypi.python.org.

  2. Wait for all the tests to pass!

  3. Merge the pull request into the master branch.

  4. Go to the bigchaindb/bigchaindb Releases page on GitHub and click the "Draft a new release" button.

  5. Fill in the details:

    • Tag version: version number preceded by v, e.g. v0.9.1
    • Target: the last commit that was just merged. In other words, that commit will get a Git tag with the value given for tag version above.
    • Title: Same as tag version above, e.g v0.9.1
    • Description: The body of the changelog entry (Added, Changed, etc.)

  6. Click "Publish release" to publish the release on GitHub.

  7. On your local computer, make sure you're on the master branch and that it's up-to-date with the master branch in the bigchaindb/bigchaindb repository (e.g. git pull upstream master). We're going to use that to push a new bigchaindb package to PyPI.

  8. Make sure you have a ~/.pypirc file containing credentials for PyPI.

  9. Do make release to build and publish the new bigchaindb package on PyPI. For this step you need to have twine installed. If you get an error like Makefile:135: recipe for target 'clean-pyc' failed then try doing

    sudo chown -R $(whoami):$(whoami) .

  10. Log in to readthedocs.org and go to the BigchainDB Server project, then:

    • Click on "Builds", select "latest" from the drop-down menu, then click the "Build Version:" button.
    • Wait for the build of "latest" to finish. This can take a few minutes.
    • Go to Admin --> Advanced Settings and make sure that "Default branch:" (i.e. what "latest" points to) is set to the new release's tag, e.g. v0.9.1. (It won't be an option if you didn't wait for the build of "latest" to finish.) Then scroll to the bottom and click "Save".
    • Go to Admin --> Versions and under Choose Active Versions, do these things:
      1. Make sure that the new version's tag is "Active" and "Public"
      2. Make sure the stable branch is not active.
      3. Scroll to the bottom of the page and click "Save".

  11. Go to Docker Hub and sign in, then:

    • Click on "Organizations"
    • Click on "bigchaindb"
    • Click on "bigchaindb/bigchaindb"
    • Click on "Build Settings"
    • Find the row where "Docker Tag Name" equals latest and change the value of "Name" to the name (Git tag) of the new release, e.g. v0.9.0.
    • If the release is an Alpha, Beta or Release Candidate release, then a new row must be added. You can do that by clicking the green "+" (plus) icon. The contents of the new row should be similar to the existing rows of previous releases like that.
    • Click on "Tags"
    • Delete the "latest" tag (so we can rebuild it)
    • Click on "Build Settings" again
    • Click on the "Trigger" button for the "latest" tag and make sure it worked by clicking on "Tags" again
    • If the release is an Alpha, Beta or Release Candidate release, then click on the "Trigger" button for that tag as well.

Congratulations, you have released a new version of BigchainDB Server!