Skip to content

Latest commit

 

History

History
361 lines (240 loc) · 13.9 KB

RELEASING.md

File metadata and controls

361 lines (240 loc) · 13.9 KB
Raw

How to release Calico

NOTE: These instructions apply only to Calico versions v3.2.0 or greater. For older releases, refer to the instructions in the corresponding release-vX.Y branch.

Overview

This repository contains documentation and packaging, but no Calico code.

Releases of this repository still serve several important purposes. Namely, they provide:

  • a single Calico release with user-facing release notes and documentation.
  • a packaging of individual Calico component releases into a single .tgz file

Prerequisites

To release Calico, you need the following permissions:

  • Write access to the core repositories in the projectcalico/ GitHub organization.

  • Push access to the Calico DockerHub repositories. Assuming you've been granted access by an admin:

    docker login

  • Push access to the Calico quay.io repositories. Assuming you've been granted access by an admin:

    docker login quay.io

  • Push access to the gcr.io/projectcalico-org repositories. Note: Some of the repos do not yet support credential helpers, you must use one of the token-based logins. For example, assuming you've been granted access, this will configure a short-lived auth token:

    gcloud auth print-access-token | docker login -u oauth2accesstoken --password-stdin https://gcr.io

  • You must be signed up as an OpenStack developer and a member of the networking-calico-release group on Gerrit.

  • You must be a member of the Project Calico team on Launchpad, and have uploaded a GPG identity to your account, for which you have the secret key.

  • You must be able to access binaries.projectcalico.org.

You'll also need several GB of disk space (~7GB for v3.4.0, for example).

Some of the release scripts also require tools to be installed in your dev environment:

  • Install and configure the GitHub hub tool.

  • Create a personal access token for Github and export it as the GITHUB_TOKEN env var (for example by adding it to your .profile).

  • Install the "GitHub release" tool, ghr:

    go get -u github.com/tcnksm/ghr

Finally, the release process assumes that your repos are checked out with name origin for the git remote for the main Calico repo.

Releasing the subcomponents

Before attempting to create a Calico release you must do the following.

  1. Choose a Calico version number, e.g. v3.2.0.

  2. Verify that the code and GitHub are in the right state for releasing for the chosen version.

  3. Select the appropriate component version numbers, and create any necessary releases. Follow the instructions in each repository for further information. (See recent release information, e.g. at https://docs.projectcalico.org/v3.7/release-notes/, for the set of components to consider releasing.)

    The following components must use the same version number as the Calico version number chosen above, and thus must be re-released for every Calico release.

    The following components do not share a version with the Calico release, but are included in the documentation.

Building and publishing packages

  1. Check out the packaging repository.

  2. In your environment, set HOST to the GCP name for binaries.projectcalico.org, GCLOUD_ARGS to the --zone and --project args needed to access that host, and SECRET_KEY to the secret key for a GPG identity that you have uploaded to your Launchpad account.

  3. Establish GCP credentials so that gcloud with HOST and GCLOUD_ARGS can access binaries.projectcalico.org.

  4. Run make release-publish VERSION=<version>, where <version> is the Calico version being released.

Preparing to cut a Calico release

  1. Check out the master branch of this repository and make sure it is up-to-date and passing Semaphore CI.

    git checkout master && git pull origin master

Your next steps depend on the type of release:

Creating a new major / minor release

Creating a docs directory prior to release

This section describes how to create a docs directory for a new major or minor release. This is typically done at the same time that release branches are cut, often well before the release is built and published.

  1. Create a new branch off of the latest master.

    git checkout -b <NEW_PERSONAL_BRANCH>

  2. Create the release-versioned directories for the documentation, copying from master directories.

    python2 ./release-scripts/do_release.py

  3. Add a new "dummy" version to the bottom of _data/versions.yml. Add a comment indicating this is to be removed when the real release is cut.

    This ensures the release is not listed as the "Latest release" in the documentation. Populate the section with tags indicating the corresponding minor release branch.

    For example:

     v2.1
   # Pre-release placeholder for Calico v2.1. Delete this when v2.1.0 goes live.
   - title: v2.1.0-pre-release
     note: ""
     components:
       typha:
         version: release-v2.1
     ... etc ...

  4. Add a section in _config.yml so that page.version will be set correctly in the new subdirectory:

    -
  scope:
    path: vX.Y
  values:
    version: vX.Y

  5. If appropriate, update the list of tested versions for different platforms in the appropriate documents.

    • Kubernetes vX.Y/getting-started/kubernetes/requirements.md
    • OpenShift vX.Y/getting-started/openshift/requirements.md
    • OpenStack vX.Y/getting-started/openstack/requirements.md
    • Host protection vX.Y/getting-started/bare-metal/requirements.md

  6. Commit your changes and submit a PR for review. For example:

    git commit -a -m "Create docs directory for vX.Y"

Building and publishing a new major/minor release

This section describes how to create a new major or minor release. It assumes that the docs directory has already been created in master as described in the section above.

  1. Create a new branch off of the latest master.

    git checkout -b <NEW_PERSONAL_BRANCH>

  2. Add the new version to the correct release section in _data/versions.yml.

  3. Update the AUTHORS.md file. This will require GITHUB_TOKEN be set in your environment.

    make update-authors

  4. Follow the steps in writing release notes to generate or update candidate release notes.

    Then, add the newly created release note file to git.

    git add _data/<VERSION>/release-notes/<VERSION>-release-notes.md

  5. (Optional) Review _config_dev.yml and edit it to exclude any previous releases that are no longer actively developed. This ensures developer builds remain fast by excluding directories which are not in active development.

  6. Commit your changes. For example:

    git commit -m "Updates for release vX.Y.Z"

  7. Push your branch and open a pull request. Get it reviewed and wait for it to pass CI.

  8. Run the following on your local branch in order to build the release at the newly created commit.

    make RELEASE_STREAM=vX.Y release

    Then, publish the tag and release to github.

    make RELEASE_STREAM=vX.Y release-publish

  9. Merge the PR. This will cause the live docs site to be updated (after a few minutes).

If the release is not a release candidate but in fact a stable release, then you must also follow the steps in the next section for promoting a release candidate to a final release.

Promoting to a final release

The following steps outline how to promote a major / minor release candidate to the latest release in the documentation. These steps should be performed after completing the steps above for building and publishing a new minor / major release.

Perform the following steps on a local branch off of the latest master.

Promoting to be the latest release in the docs

  1. Add a new <li> entry to the <span class="dropdown"> in _layouts/docwithnav.html file.

  2. Modify the redirect in /index.html to point to your new release.

  3. Move the section for the release in _data/versions.yml to the top of the file so that it will be the 'Latest Release', and remove any release candidates or dummy releases from the section.

  4. Run make add_redirects_for_latest VERSION=vX.Y to update the redirects.

  5. Commit your current changes.

Updating canonical redirects

  1. Pull the latest master and check out a new branch.

  2. Run this command to update canonical URLs:

    make update_canonical_urls

  3. Submit a PR with the canonical link changes, make sure it passes CI, and get it reviewed and merged.

Performing a "patch" release

Creating the release

  1. On a new branch, add the new version to the correct release section in _data/versions.yml

  2. Follow the steps in writing release notes to generate candidate release notes.

    Then, add the newly created release note file to git.

    git add _data/<VERSION>/release-notes/<VERSION>-release-notes.md

  3. Commit your changes. For example:

    git commit -m "Updates for release vX.Y.Z"

  4. Push your branch and open a pull request. Get it reviewed and wait for it to pass CI.

  5. Once reviewed and CI is passing, run the following on your local branch in order to build and publish the release at the newly created commit.

    make RELEASE_STREAM=vX.Y release

    Then, publish the tag and release.

    make RELEASE_STREAM=vX.Y release-publish

  6. Merge the PR. This will cause the live docs site to be updated (after a few minutes).

Release notes

Release notes for a Calico release contain notable changes across Calico repositories. To write release notes for a given version, perform the following steps.

  1. Check the merged pull requests in the milestone and make sure each has a release note if it needs one.

    Use this URL to query for PRs, replacing vX.Y.Z with your desired version.

    https://github.com/issues?utf8=%E2%9C%93&q=user%3Aprojectcalico+milestone%3A%22Calico+vX.Y.Z%22+

    Each PR that wants a release note must meet the following conditions to have its release note considered:

    • It is in the correct Calico vX.Y.Z GitHub milestone
    • It has the release-note-required label
    • It has one or more release notes included in the description (Optional).

  2. Run the following command to collect all release notes for the given version.

    make RELEASE_STREAM=vX.Y release-notes

    A file called <VERSION>-release-notes.md will be created with the raw release note content.

    NOTE: If you receive a ratelimit error, you can specify a GITHUB_TOKEN in the above command to increase the number of allowed API calls. See here for details.

  3. Edit the generated file.

    The release notes should be edited to highlight a few major enhancements and their value to the user. Bug fixes and other changes should be summarized in a bulleted list at the end of the release notes. Any limitations or incompatible changes in behavior should be explicitly noted.

    Consistent release note formatting is important. Here are some examples for reference: