Release Process

Overview

The release process consists of two phases: versioning and publishing the release.

Versioning involves maintaining the following files:

CHANGELOG.md - this file contains a list of all the important changes in each release.
Makefile - the Makefile contains a VERSION variable that defines the version of the project.

The steps below explain how to update these files. In addition, the repository should be tagged with the semantic version identifying the release.

Publishing involves creating a new Release on GitHub with the relevant CHANGELOG.md snippet and uploading the binaries from the build phase.

Note: This release process is subject to change without notice.

Release Cadence

There are two version tracks for the OPA project:

Release Candidate (vX.Y.Z-rc.A)
Stable (vX.Y.Z)

A new version of OPA is scheduled to release on the last Friday of every month. At the beginning of that week, we will create a release candidate branch (release-<major>.<minor>-rc.0) from the main branch and create a release candidate tag (v<major>.<minor>.0-rc.0) based on the release candidate branch for pre-release. Once the pre-release is published, users are encouraged to try out the features, bug fixes in the release candidate. If regressions or bugs are detected, they need to get fixed before cutting the stable release. We do not recommend using OPA release candidates in a production environment. The stable release that comes out after the release candidate may be identical to the release candidate if no other features or bug fixes are introduced to the main branch in between.

See the next section for details on cutting an individual release.

Versioning

The steps below assume an OPA development environment has configured for the standard GitHub fork workflow. See OPA Dev Instructions

The following steps assume a remote named upstream exists that references the OPA source repository. As needed, add an upstream remote for the repository:
sh
```
git remote add upstream [email protected]:open-policy-agent/opa.git
git fetch --tags upstream
```
Note: This stage can fail if you have not registered an SSH key on your Github account.
Create a release branch off of main, to ensure you don't mangle your fork while creating the release:
```
git checkout -b release-v<version> origin/main
```
Create a personal access token for GitHub with the 'read:org' scope. Export it to the GITHUB_TOKEN environment variable.
Execute the release-patch target to generate boilerplate patch. Give the semantic version of the release:
```
make release-patch VERSION=0.12.8 > ~/release.patch
```
Apply the release patch to the working copy and preview the changes:
```
patch -p1 < ~/release.patch
git diff
```
Amend the changes as necessary, e.g., many of the Fixes and Miscellaneous changes may not be user facing (so remove them). Also, if there have been any significant API changes, call them out in their own sections.

Commit the changes and push to remote repository fork.

git add .
git commit -s -m "Prepare v<version> release"
git push origin release-v<version>

Create a Pull Request for the release preparation commit.
Once the Pull Request has merged fetch the latest changes and tag the commit to prepare for publishing:
```
git fetch upstream
git tag v<semver> upstream/main
```
Note: Ensure that tag is pointing to the correct commit ID! It must be the merged release preparation commit.

Create a new branch for the dev-patch work:

git checkout -b dev-v<next_semvar> origin/main

Execute the dev-patch target to generate boilerplate patch. Give the semantic version of the next release:
```
make dev-patch VERSION=0.12.9 > ~/dev.patch
```
The semantic version of the next release typically increments the point version by one.
Apply the patch to the working copy and preview the changes:
```
patch -p1 < ~/dev.patch
git diff
```

Commit the changes and push to remote repository fork.

git commit -a -s -m "Prepare v<next_semvar> development"
git push origin dev-v<next_semvar>

Create a Pull Request for the development preparation commit.

Publishing

Push the release tag to remote source repository.
```
git push upstream v<semver>
```
Note: Only OPA maintainers will have permissions to perform this step.
Open browser and go to https://github.com/open-policy-agent/opa/releases
Update the draft release (may take up to 20 min for the draft to become available, track its process under https://github.com/open-policy-agent/opa/actions). Ensure everything looks OK and publish when ready.

Notes

The openpolicyagent/opa Docker image is automatically built and published to Docker Hub as part of the Travis-CI pipeline. There are no manual steps involved here.
The docs and website should update and be published automatically. If they are not you can trigger one by a couple of methods:
- Login to Netlify (requires permission for the project) and manually trigger a build.
- Post to the build webhook via:
  bash
```
curl -X POST -d {} https://api.netlify.com/build_hooks/612e8941ffe30d2902bcce80
```
The Algolia search index is automatically updated when the site is crawled daily at 20:30 (UTC). The crawling process takes around 25 minutes to complete and can be triggered from crawler.algolia.com (login details required).

Bugfix Release Process

The following steps assume a remote named upstream exists that references the OPA source repository. As needed, add an upstream remote for the repository:

git remote add upstream [email protected]:open-policy-agent/opa.git
git fetch --tags upstream

If this is the first bugfix for the release, create the release branch from the release tag and push to the source repository.

bash

git checkout -b release-0.14 v0.14.0
git push upstream release-0.14

Otherwise, checkout the release branch and sync with upstream (as needed):

bash

git fetch upstream
git checkout release-0.14
git reset --hard upstream/release-0.14

Cherry pick the changes from main or other branches onto the bugfix branch:

bash

git cherry-pick -x <commit-id>

Using -x helps to keep track of where the commit came from originally

Update the VERSION variable in the Makefile and CHANGELOG, same workflow as a normal release.

bash

make release-patch VERSION=0.14.1 > ~/release.patch

Apply the patch to the working copy and preview the changes:

bash

patch -p1 < ~/release.patch
git diff

The generated CHANGELOG will likely need some manual adjustments for bugfix releases!

Commit this change and push to fork:

bash

git commit -s -a -m 'Prepare v0.14.1 release'
git push origin release-0.14

Open a Pull Request against the upstream release branch. Be careful to open the Pull Request against the correct upstream release branch. DO NOT open/merge the Pull Request into main or other release branches.

Note: Make sure to do a "Rebase and merge" and NOT a squash when merging the PR, to preserve the cherry-picked commits. Alternatively, the cherry-picks can be pushed to upstream before submitting the PR.

Once the Pull Request has merged fetch the latest changes and tag the commit to prepare for publishing. Use the same instructions as defined above in normal release publishing guide (being careful to tag the appropriate commit).

Last step is to copy the CHANGELOG snippet and generated files (builtin_metadata.json and capabilities.json) for the version to main. Create a new PR with the version information added below the Unreleased section. Remove any Unreleased notes if they were included in the bugfix release.