Skip to content

RELEASING.md

Latest commit

 

History

History
110 lines (72 loc) · 6.56 KB

RELEASING.md

File metadata and controls

110 lines (72 loc) · 6.56 KB

Releasing Guide for Kroxylicious

This document describes how to release this component.

The component is released using GitHub automation.

At a high level, the process is as follows:

  1. The developer prepares the release blog post.
  2. The developer adds their private key/passphrase as repository secrets
  3. The workflow stage_release tags, builds/signs the release, and stages the release on a Maven Central Portal. This process uses the GitHub machine account kroxylicious-robot and a user token owned by Sonatype account kroxylicious account.
  4. The staged release is verified using manual verification steps.
  5. The release is made public.
  6. The developer removes their private key/passphrase from the repository secrets.

Prerequisites

You must be a member of the Kroxylicious release-engineers and have access to create secrets within the kroxylicious repository.

You must be registered with Sonatype Central Portal and your id must be registered as publisher for the Kroxylicious namespace. To do the latter step, ask someone who is a publisher to open a support ticket.

You will need a GPG key, follow this guide.

You will need to upload your GPG public key to some keyservers. You can follow this which explains how to obtain your public key. Upload that key to the following keyservers:

Create-or-update the following repository secrets:

Secret Description
KROXYLICIOUS_RELEASE_PRIVATE_KEY Private key, in armor format, of the project admin conducting the release.
KROXYLICIOUS_RELEASE_PRIVATE_KEY_PASSPHRASE Passphrase used to protect the private key
KROXYLICIOUS_RELEASE_TOKEN GitHub PAT with write permissions for content, commit status, pull-requests for this repository and the kroxylicious.github.io repository

To export your key run something like

gpg --armor --export-secret-key ${KEY_ID} | pbcopy

While pbcopy is macOS specific, similar utilities exist for Linux see StackExchange

Prepare the release blog post

Prepare the release blog post by opening a PR kroxylicious.github.io. Get the PR reviewed by your peers, addressing any comments, until the content is agreed. Don't merge it yet.

Release steps

Use the Kroxylicious Team Developers Slack Channel to coordinate the release with the other developers. It is important no other work is merged to main during the release.

Stage the Release

Run stage_workflow. Set the release-version argument to the version being release e.g. 0.7.0.

This will:

  • raise single PR that will contain two commits:
    1. the first will version the artefacts at release-version. A release-version tag will point at this commit.
    2. the second will re-open main for development, at the next snapshot.
  • stage a deployment in the Central Publishing Portal.

If anything goes wrong, follow the steps in Failed Releases

Verify the Release

You can validate the staged artefacts by using a test application, T, use the Maven artefacts. The kroxylicious-wasm from the community-gallery is a suitable choice.

  1. Configure Maven to download staged artefacts from Central Publishing Portal. To do this, you need to generate a user token for your Sonatype account and then [configure maven] (https://central.sonatype.org/publish/publish-portal-api/#manually-testing-a-deployment-bundle) to use it.

  2. Run T build/test cycle but use an alternative cache location to be sure artefacts are being fetched. Check the build output, you'll see the kroxylicious comes from the staging location.

MAVEN_OPTS="-Dmaven.repo.local=/tmp/repository" mvn verify -Dkroxylicious.version=<new release version>

If the build passes, proceed to make the release public. The local changes made to T's POM can be reverted.

  1. Once you've finished verifying the release, revoke your Sonatype token.

Making the release public

  1. Comment on the PR @kroxylicious-robot promote-release.
  2. Let Kroxylicious Team Developers know the release is finished.
  3. Publish the documentation for the release
  4. Merge the blog post PR
  5. Post to social media about the release.

If anything goes wrong, follow the steps in Failed Releases

Failed Releases

If the release fails verification, comment on the PR @kroxylicious-robot drop-release. This will drop the snapshot repository, delete the release notes and close PR.

Remove your private key/passphrase

Update the private key/passphrase secrets from the repository secrets to whitespace.