Release Management

This page has the instructions to prepare and make a new release of OpenEBS documentation.

Overview

OpenEBS Docs always point to the latest release and content is provided from the master. The older release documentation is built from the release specific branch like v1.7.x and so forth.

The content for the upcoming release will be merged into staging branch.

The following steps are performed when making a new release.

Step 1: Create a release branch for the previous release.

For example, when releasing 1.8, the master will contain documentation for 1.7. So Create a new branch 1.7.0 from master

Step 2: Setup CI for the newly created release branch.

In the release branch, edit travis.yaml to update the release branch builds. Replace the version x.y.z with release branch name. (Assuming the release branch is 1.7.0). The modified line should look like:

     - if [ "$TRAVIS_BRANCH" = "1.7.0" -a "$TRAVIS_PULL_REQUEST" = "false" ]; then export REPO=mayadataio/openebsdocsversion;
         docker login -u "$DOCKER_USER" -p "$DOCKER_PASS" && docker build -t $REPO:$TRAVIS_BRANCH-$COMMIT . && docker push $REPO;
       fi

In the release branch, modify the references to the current release with the release path. For 1.7.0 release, use the release path as v170.

• Edit website/siteConfig.js and set baseUrl to the release path. Example baseUrl: '/v170/'

• Edit website/versions.json and set the release path.

• Edit all the content files under docs to point to the release path. Example /docs/ should be changed to /v170/docs/. You can use a script located in openebs-docs/hack/update_release.sh. Update the regular expression with the required version.

  cd docs/
  ../hack/update_release.sh
  

• Edit the releases.md to remove recommended release for the older release.

• Edit the overview.md to add a deprecation notice like below:

  <center><p style="padding: 20px; margin: 20px 0; border-radius: 3px; background-color: #eeeeee;"><strong>
  Documentation for OpenEBS v1.7.0 is no longer actively maintained. The version you are currently viewing is a static 
  snapshot. Click here for the [latest](https://docs.openebs.io) version.
  </strong></p></center>
  

Step 3: Launch a portal for previous release content.

The doc website are hosted in GKE via Flux. Flux will watch for deployments under

• Create a deployment and service for release content. For 1.7.0, create v1.7.0-docs-openebs.yaml under https://github.com/cloudbytestorage/mayadata-cicd

• Check the docker image pushed from the release by travis. https://travis-ci.com/github/openebs/openebs-docs. Fetch the image tag after the Step 2 changes are all merged.

• You can copy from the previous copy of the deployment service and update the release names and the image tag.

• Add a new path based ingress for release branch content. Edit https://github.com/cloudbytestorage/mayadata-cicd/blob/master/nginx-ingress-gke.yaml Make the changes under the section: host: docs.openebs.io. Add a new path like below:

     - path: /v170/
            backend:
              serviceName: v1-7-0docs-openebs-service
              servicePort: 80
  

• Once the above PRs for deployment and ingress path are merged, verify that the docs for the previous release are accessible. For 1.7.0, the docs should be available at https://docs.openebs.io/v170/docs/next/overview.html

Step 4: Update staging with current release information.

By this stage, all the pending PRs into the current release should be merged into staging. Raise a new PR to staging that updates the information to point to the current release. This involves the following:

• update the site dropdown to include previous release (website/versions.json)
• update references from the previous release to the current release (docs/*.md)
• update release notes for the current release (docs/releases.md)

Step 5: Merge changes from staging to master

• Once all the staging PRs are merged, raise a PR from staging to master.
• After the changes are merged, verify that https://docs.openebs.io reflects the latest release changes.
• Sync commit hash between staging and master as described in https://github.com/openebs/openebs-docs/wiki/Publishing-new-changes.