mirror of https://github.com/grafana/loki
docs: update release docs (#12511)
Trevor Whitney
2 years ago
committed by
GitHub
parent
4404f7d2f7
commit
a47df1ebfd
@ -0,0 +1,47 @@ |
||||
--- |
||||
title: Prepare Major Release |
||||
description: Describes the process to create a workflow for a major release of Grafana Loki. |
||||
--- |
||||
|
||||
# Prepare Major Release |
||||
|
||||
A major release follows the same process as [minor and patch releases]({{< relref "./prepare-release.md" >}}), but requires a custom workflow to be created to run on the branch we want to release from. The reason for this is that we don't do major releases very often, so it is not economical to keep those workflows running all the time. |
||||
|
||||
To create a major release workflow, follow the steps below. |
||||
|
||||
1. Edit `./github/release-workflows.jsonnet` |
||||
1. Add a new workflow for the major release. For example, the 3.0 release looked like the following: |
||||
|
||||
```jsonnet |
||||
'three-zero-release.yml': std.manifestYamlDoc( |
||||
lokiRelease.releasePRWorkflow( |
||||
branches=['release-3.0.0'], |
||||
buildImage=buildImage, |
||||
checkTemplate=checkTemplate, |
||||
golangCiLintVersion=golangCiLintVersion, |
||||
imageBuildTimeoutMin=imageBuildTimeoutMin, |
||||
imageJobs=imageJobs, |
||||
imagePrefix=imagePrefix, |
||||
releaseLibRef=releaseLibRef, |
||||
releaseRepo='grafana/loki', |
||||
skipArm=false, |
||||
skipValidation=false, |
||||
useGitHubAppToken=true, |
||||
releaseAs='3.0.0', |
||||
) + { |
||||
name: 'Prepare Loki 3.0 release', |
||||
}, false, false |
||||
), |
||||
|
||||
``` |
||||
|
||||
1. Make sure the `branches` field is set to the release branch you want to release from. |
||||
1. Make sure the `releaseAs` field is set to the version you want to release. |
||||
1. Run `make release-workflows` to generate the new workflow. Merge this change to both the main and release branch. You may also want to disable the patch release workflow as part of this PR, see below. |
||||
|
||||
## Race Condition with Patch Release |
||||
|
||||
Once this new workflow is created there is a bit of a race condition with the patch workflow. This can be resolved in 1 of 2 ways: |
||||
|
||||
1. Disable the patch release workflow until after the major release is complete. |
||||
1. Watch all actions for the release branch (ie. <https://github.com/grafana/loki/actions?query=branch%3Arelease-3.0.x>) and cancel and patch release runs. |
||||
@ -0,0 +1,26 @@ |
||||
--- |
||||
title: Merge Release PR |
||||
description: Describes the process to release Loki by merging the release PR. |
||||
--- |
||||
# Merge Release PR |
||||
|
||||
To release Loki, merge the release PR. This PR will have the title `chore(<BRANCH>): release <VERSION>`. Here's what the 3.0 release PR looked like. |
||||
|
||||
 |
||||
|
||||
3.0 was the first major release using this new process, and enforcing conventional commits was relatively new. Going forward the release notes in the release PR will be much more thorough, as we're now enforcing that every PR has a conventional commit message. |
||||
|
||||
To test the artifacts before releasing, you can download the artifacts from the link in the footer of the PR description. Merging the PR will: |
||||
|
||||
1. Fetch the built artifacts. |
||||
1. Create a draft GitHub release with the release notes in the PR description. |
||||
1. Upload fetched binareis to the draft release. |
||||
1. Publish fetched images to Docker Hub as multi-arch images. |
||||
1. Publish the draft release and create the GitHub tag. |
||||
1. (Optionally) Mark the release as the latest if it represents the newest version of Loki. |
||||
|
||||
## Troubleshooting / Retrying Release |
||||
|
||||
If something goes wrong with the release automation, you may need to rerun the job. This may require updating the release code in the `grafana/loki` repo via a PR, or it may include updating the code in `grafana/loki-release` that the release pipeline fetches. In either case, if you need to re-release a merge release PR, you'll need to remove the `autorelease: tagged` label from that PR and add the `autorelease: pending` label. The automation relies on these labels to determine which merged PRs have and have not yet been released. After fixing the labels, re-run the release workflow, and it should correctly get passed the `should-release` step. The release process is idempotent, so if a draft release has already been created via a previously failed release, the process will continue, re-upload the binaries, and re-publish the images. |
||||
|
||||
Once the release is finished, you may need to manually flip the label back to `autorelease: tagged`. |
||||
@ -1,33 +0,0 @@ |
||||
--- |
||||
title: Prepare Changelog |
||||
description: Prepare Changelog |
||||
--- |
||||
# Prepare Changelog |
||||
|
||||
Changelog is the list of all the important changes (features, bug-fix, optimizations, docs) that are part of particular Loki release. |
||||
|
||||
## Before you begin |
||||
|
||||
1. Determine the [VERSION_PREFIX]({{< relref "./concepts/version" >}}). |
||||
|
||||
1. The changelog in Grafana Loki works as follows. |
||||
|
||||
We have `CHANGELOG.md` that records both unreleased and released changes. |
||||
|
||||
Preparing changelog for Loki release at high level is basically two steps |
||||
1. Move `unreleased` changes to specific version on `release-VERSION_PREFIX` branch. |
||||
1. Reflect those changes on `main` branch. |
||||
|
||||
## Steps |
||||
|
||||
1. Make sure the `CHANGELOG` on `release-VERSION_PREFIX` branch is up to date. |
||||
|
||||
1. Check the commits diffs between the new version (example: 2.9.x) and the most recent older version (example: 2.8.x) via |
||||
``` |
||||
https://github.com/grafana/loki/compare/release-2.8.x...release-2.9.x |
||||
``` |
||||
1. Check if any of those commits are important enough to add to the `CHANGELOG`. |
||||
|
||||
1. On the `release-VERSION_PREFIX` branch promote `Main/Unreleased` to `VERSION (YYY-MM-DD)`. Example [PR](https://github.com/grafana/loki/pull/10470). |
||||
|
||||
1. On the `main` branch remove entries from `Main/Unreleased` that are already part of `VERSION (YYY-MM-DD)`. Example [PR](https://github.com/grafana/loki/pull/10497). |
||||
@ -1,50 +0,0 @@ |
||||
--- |
||||
title: Prepare Release notes |
||||
description: Prepare Release notes |
||||
--- |
||||
# Prepare Release notes |
||||
|
||||
Release notes are the few key highlights of the release. This is what appears on the release page on Github. |
||||
|
||||
## Before you begin |
||||
|
||||
1. Determine the [VERSION_PREFIX]({{< relref "./concepts/version" >}}). |
||||
|
||||
1. The release notes process for Grafana Loki works as follows. |
||||
|
||||
We have two separate markdown files: |
||||
1. `release-notes/next.md` to track release notes that are not released yet. |
||||
1. `release-notes/v<major>-<minor>.md` to track release notes that are part of each specific Loki version. |
||||
|
||||
Preparing release notes for a specific Loki release at high level is basically two steps: |
||||
1. Add important notes to `next.md` |
||||
1. And make it available in a specific Loki version. |
||||
|
||||
## Steps |
||||
|
||||
**This section is out of date now that we use conventional commits, to be updated (Trevor/Callum)** |
||||
|
||||
1. Discuss with Loki team to finalize what PRs should be part of release notes. |
||||
|
||||
1. Go to the PR and add a label `add-to-release-notes`. Example [PR](https://github.com/grafana/loki/pull/10213) with label added. |
||||
|
||||
{{% admonition type="note" %}} |
||||
Pick any one PR if the changes involves multiple PRs. |
||||
{{% /admonition %}} |
||||
|
||||
1. The CI process creates a PR to add the original PR to the release notes. Example [PR](https://github.com/grafana/loki/pull/10359). |
||||
|
||||
1. Review the PR carefully. Update the description, approve and merge. |
||||
|
||||
1. Repeat the steps for all the PRs. |
||||
|
||||
1. Review the final release notes with Loki squad. |
||||
|
||||
1. Create a release notes PR on the `main` branch. Example [PR](https://github.com/grafana/loki/pull/9004/). |
||||
* Copy `next.md` file to the new file `v<MAJOR>-<MINOR>.md` (e.g: `v2.9.md`) |
||||
* Replace version place holders `V?.?` with `V<MAJOR>.<MINOR>` in the new file. |
||||
* Remove all the entries under `Features and enhancements`, `Upgrade Considerations` and `Bug fixes` in `next.md` file |
||||
* Add an entry for the new version in `_index.md` as shown in the example PR above. Set the weight for the new file so that the new release notes file appears at the top of the table of contents. |
||||
* Get the PR reviewed and merged. |
||||
|
||||
1. Backport the release notes PR from `main` to the `release-VERSION_PREFIX` branch. Example [PR](https://github.com/grafana/loki/pull/10482). |
||||
@ -0,0 +1,16 @@ |
||||
--- |
||||
title: Prepare Release |
||||
description: Describes the prepare release pipeline that prepares release PRs for Grafana Loki. |
||||
--- |
||||
# Prepare Release |
||||
|
||||
Releasing Grafana Loki consists of merging a long-running release PR. Two workflows keep these PRs up to date, one for patch releases (which runs on commits to branches matching `release-[0-9]+.[0-9]+.x`) and one for minor releases (which runs on commits to branches matching `k[0-9]+`). These pipelines use release please to do the following: |
||||
|
||||
1. Run tests and linting |
||||
1. Build binaries and images for the proposed release version |
||||
1. Generate release notes based on conventional commits since the last release |
||||
1. Create or update the long-running release PR for that release, indicating which commit will be released if the PR is merged with a link to the built artifacts that will be published. |
||||
|
||||
## Major releases |
||||
|
||||
Major releases follow the same process as minor and patch releases, but require a custom workflow to be created to run on the branch we want to release from. The reason for this is that we don't do major releases very often, so it is not economical to keep those workflows running all the time.To create a major release workflow, follow the steps in the [major release workflow]({{< relref "./major-release.md" >}}) document. |
||||
@ -1,28 +0,0 @@ |
||||
--- |
||||
title: Publish Release |
||||
description: Publish Release |
||||
--- |
||||
# Publish Release |
||||
|
||||
This is how to publish the release in GitHub. |
||||
|
||||
## Before you begin |
||||
|
||||
1. You should see a new draft release created [here](https://github.com/grafana/loki/releases). If not, go back to [Tag Release]({{< relref "./tag-release" >}}). |
||||
|
||||
## Steps |
||||
|
||||
1. Edit the release draft by filling in the `Notable Changes` section with all the changes from the release notes for this release (from the `docs/sources/release-notes/` directory). |
||||
|
||||
1. Add a footer to the `Notable Changes` section: |
||||
|
||||
`For a full list of changes, please refer to the [CHANGELOG](https://github.com/grafana/loki/blob/RELEASE_VERSION/CHANGELOG.md)!` |
||||
|
||||
Do not substitute the value for `CHANGELOG`. |
||||
|
||||
1. At the bottom of the release page, perform the following: |
||||
- For a Stable Release or Patch Release, tick the checkbox to "set as the latest release" only if it's the latest release on current latest `release-VERSION_PREFIX` branch. |
||||
|
||||
2. Optionally, have other team members review the release draft if you wish to feel more comfortable with it. |
||||
|
||||
3. Publish the release! |
||||
|
After Width: | Height: | Size: 828 KiB |
@ -1,53 +0,0 @@ |
||||
--- |
||||
title: Tag Release |
||||
description: Tag Release |
||||
--- |
||||
# Tag Release |
||||
|
||||
A tag is required to create GitHub artifacts and as a prerequisite for publishing. |
||||
|
||||
## Before you begin |
||||
|
||||
1. All required commits for the release should exist on the release branch. This includes functionality and documentation such as the [release notes]({{< relref "./prepare-release-notes" >}}) and [CHANGELOG.md]({{< relref "./prepare-changelog" >}}). All versions in the repo should have already been [updated]({{< relref "./update-version-numbers" >}}). |
||||
|
||||
1. Make sure you are up to date on the release branch: |
||||
|
||||
``` |
||||
git checkout release-VERSION_PREFIX |
||||
git fetch origin |
||||
git pull origin |
||||
``` |
||||
|
||||
1. Determine the [VERSION_PREFIX]({{< relref "./concepts/version" >}}). |
||||
|
||||
1. Follow the GitHub [instructions](https://docs.github.com/en/authentication/managing-commit-signature-verification) to set up GPG for signature verification. |
||||
|
||||
1. Optional: Configure git to always sign on commit or tag. |
||||
|
||||
```bash |
||||
git config --global commit.gpgSign true |
||||
git config --global tag.gpgSign true |
||||
``` |
||||
|
||||
If you are on macOS or Linux and using an encrypted GPG key, `gpg-agent` or `gpg` may be unable to prompt you for your private key passphrase. This will be denoted by an error when creating a commit or tag. To circumvent the error, add the following into your `~/.bash_profile`, `~/.bashrc` or `~/.zshrc`, depending on which shell you are using. |
||||
|
||||
``` |
||||
export GPG_TTY=$(tty) |
||||
``` |
||||
|
||||
## Steps |
||||
|
||||
1. Tag the release: |
||||
|
||||
Example commands: |
||||
|
||||
``` |
||||
RELEASE="v$VERSION" # e.g: v2.9.0 |
||||
git tag -s $RELEASE -m "tagging release $RELEASE" |
||||
git push origin $RELEASE |
||||
``` |
||||
|
||||
1. After a tag has been pushed, GitHub CI will create release assets and open a release draft for every pushed tag. |
||||
- This will take ~10-20 minutes. |
||||
- You can monitor this by viewing the drone build on the commit for the release tag. |
||||
- It also creates a PR to update the Helm charts. Example [PR](https://github.com/grafana/loki/pull/10479). Review and merge it. |
||||
Loading…
Reference in new issue