--- ---

Release Process (General)

Integration and deployment/delivery process for DocOps Lab sites and artifacts.

This page supports fixing the version numbers used in the release procedure steps. Adjust as needed.

DocOps Lab projects follow a consistent, if always progressing, architecture and development/release process.

This guide focuses on the release process.

Prerequisites

Technologies Overview

DocOps Lab projects are primarily Ruby gems, usually with associated Docker images that provide proper environments for the CLI associated with the project gem.

Ruby is used mainly because of its excellent AsciiDoc tooling through Asciidoctor, with an accompanying preference for Jekyll static-site generator and Liquid templating language, all of which are Ruby native.

Docker is employed by internal developers and end users of DocOps Lab tooling alike, to reduce if not eliminate the Ruby maintenance overhead.

Required Tools

If you are brand new to the world of code, Git, and GitHub, DocOps Lab will soon have resources aimed precisely at your experience level. For now, some experience with these tools is assumed.

Must-haves
Should-haves

  • GitHub CLI (gh)

  • a code editor that supports Ruby, AsciiDoc, and YAML
    (Try VS Code if you don’t have a preference yet.)

Ruby Environment

Ruby dependencies are managed through Bundler using each project’s Gemfile/.gemspec definitions.

A proper Ruby environment and all common (cross-project) development dependencies are supplied in the docopslab/dev Docker image. Containers run from this image provide unified linting, git hooks, and development tooling used by most DocOps Lab codebases.

These quality-control tools are also built into all GitHub repos via GH Actions workflows, local availability is not required just to work on or contribute to a DocOps Lab codebase.

See DocOps Lab Dev-tooling Setup for comprehensive setup details if you are initializing a new DocOps Lab project.

Required Credentials

Use environment variables to store sensitive credentials securely. These credentials are only needed during the release process, not the development phase.

  • RubyGems API Key

  • Docker Hub Credentials

    • Organization: docopslab

    • DockerHub account with write permissions for docopslab images

    • Set as: DOCKERHUB_USERNAME, DOCKERHUB_TOKEN

  • GitHub Token (some projects only)

    • Scope: repo

    • Set as: DOCOPSLAB_GITHUB_TOKEN or GITHUB_TOKEN

Platform Setup

Deployment platforms must be initialized for each new project, as instructed in Product Artifact and Documentation Deployment Setup.

Release Procedure

Manual Double-Checks

  • No local paths in Gemfile.

  • All documentation changes merged.

  • Version attribute bumped and propagated.

Conditions ("Definition of Done")

  • All target issues are closed.

  • CI builds and tests pass on dev/x.y.

  • Documentation updated and merged.

Step 1. Prepare Release History

Generate release notes and changelog using ReleaseHx.

bundle update releasehx
bundle exec releasehx <$tok.majmin>.<$tok.patch> --md docs/release/<$tok.majmin>.<$tok.patch>.md

Edit the Markdown file at docs/release/<$tok.majmin>.<$tok.patch>.md.

This step may vary significantly depending on project’s implementation of ReleaseHx.

See the project’s README.adoc; seek for releasehx.

Step 2. Merge to Main

git checkout main
git pull origin main
git merge --no-ff dev/<$tok.majmin>
git push origin main

Step 3. Tag Release

git tag -a v<$tok.majmin>.<$tok.patch> -m "Release <$tok.majmin>.<$tok.patch>"
git push origin v<$tok.majmin>.<$tok.patch>

Step 4. Create GitHub Release

Use the GitHub CLI to create a release:

gh release create v<$tok.majmin>.<$tok.patch> --title "Release <$tok.majmin>.<$tok.patch>" --notes-file docs/releases/<$tok.majmin>.<$tok.patch>.md --target main

Or else use the GitHub web interface to manually register the release, and copy/paste the contents of docs/releasehx/<$tok.majmin>.<$tok.patch>.md into the release notes field.

Step 5. Publish Remaining Artifacts

Use the publish.sh script with proper credentials in place.

./scripts/publish.sh

This step concludes the release process.

Post-Release Tasks

  • Cut a release branch for patching (release/<$tok.majmin>).

  • Update :next_prod_vrsn: in docs.

  • Create next development branch (dev/<next>).

  • Notify stakeholders.

Patch Procedure

Rollback Failsafe

If a release must be rolled back and retracted, you must revert the changes and “yank” the artifacts.

git tag -d v<$tok.majmin>.<$tok.patch>
git push origin :refs/tags/v<$tok.majmin>.<$tok.patch>
git revert -m 1 <merge-commit>
git push origin main

Retract or yank the artifacts (DockerHub, RubyGems, etc) and nullify the GH release.

gh release delete v<$tok.majmin>.<$tok.patch>
gem yank --version <$tok.majmin>.<$tok.patch> <gemname>
docker rmi <image>:<$tok.majmin>.<$tok.patch>

Be sure to un-publish any additional artifacts specific to the project.

Standard Patching

Perform patch work against the earliest affected release/x.y. These examples use 1.1, 1.2, and 1.2.1 as example versions.

Patch development procedure
git checkout release/1.1
git checkout -b fix/parser-typo
# … FIX …
git add .
git commit -m "fix: correct parser typo"
git push origin fix/parser-typo
# … TEST …
git checkout release/1.1
git merge --squash fix/parser-typo
git commit -m "fix: correct parser typo"
git push origin release/1.1
git tag -a v1.2 -m "Patch release 1.2"
git push origin v1.2
Example forward porting procedure
git checkout release/1.2
git cherry-pick <commit-hash>
# … TEST …
git push origin release/1.2
git tag -a v1.2.1 -m "Patch release 1.2.1"
git push origin v1.2.1
Be sure to change 1.1, 1.2, and 1.2.1 to the actual affected branches and versions.

Repeat for every affected branch then release the patched versions.

Between minor versions, patch versions may vary due to inconsistent applicability of patches.

Patch Releasing

Perform Steps 1, 4, and 5 of the standard release procedure: