hanzo/logs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs/scripts: Update Loki OSS release guide (#10646)

Browse Source 
**What this PR does / why we need it**:
Update Loki OSS release guide

This is based on the learnings from recent minor version release v2.9.0

Changes:
1. Update the release docs and organise it in a way it's usable for both
stable and patch release
2. Scripts updates

**Which issue(s) this PR fixes**:
Fixes #<issue number>

**Special notes for your reviewer**:

**Checklist**
- [x] Reviewed the
[`CONTRIBUTING.md`](https://github.com/grafana/loki/blob/main/CONTRIBUTING.md)
guide (**required**)
- [x] Documentation added

---------

Signed-off-by: Kaviraj <kavirajkanagaraj@gmail.com>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
This commit is contained in:
Kaviraj Kanagaraj
2023-09-21 09:58:21 +02:00
committed by GitHub
co-authored by github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
parent aed39c89ee
commit 446502bad0
13 changed files with 401 additions and 122 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/sources/community/maintaining/release.md
-122
View File
@@ -1,122 +0,0 @@
---
title: Releasing Grafana Loki
description: Releasing Grafana Loki
aliases:
- ../../maintaining/release/
---
# Releasing Grafana Loki
This document is a series of instructions for core Grafana Loki maintainers to be able
to publish a new Loki release.
## Prerequisites
Each maintainer performing a release should perform the following steps once
before releasing Loki.
### Signing Tags and Commits
#### Add Existing GPG Key to GitHub
First, Navigate to your user's [SSH and GPG keys settings
page](https://github.com/settings/keys). If the GPG key for the email address
used to commit with Loki is not present, follow these instructions to add it:
1. Run `gpg --armor --export <your email address>`
1. Copy the output.
1. In the settings page linked above, click "New GPG Key".
1. Copy and paste the PGP public key block.
#### Signing Commits and Tags by Default
To avoid accidentally publishing a tag or commit without signing it, you can run
the following to ensure all commits and tags are signed:
```bash
git config --global commit.gpgSign true
git config --global tag.gpgSign true
```
##### macOS Signing Errors
If you are on macOS and using an encrypted GPG key, the `gpg-agent` 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` or `~/.zshrc`, depending on which shell you are
using:
```
export GPG_TTY=$(tty)
```
## Performing the Release
1. Create a new branch to update `CHANGELOG.md` and references to version
numbers across the entire repository (e.g. README.md in the project root).
1. Modify `CHANGELOG.md` with the new version number and its release date.
1. List all the merged PRs since the previous release. This command is helpful
for generating the list (modifying the date to the date of the previous release): `curl https://api.github.com/search/issues?q=repo:grafana/loki+is:pr+"merged:>=2019-08-02" | jq -r ' .items[] | "* [" + (.number|tostring) + "](" + .html_url + ") **" + .user.login + "**: " + .title'`
1. Go through `docs/` and find references to the previous release version and
update them to reference the new version.
1. *Without creating a tag*, create a commit based on your changes and open a PR
for updating the release notes.
1. Until [852](https://github.com/grafana/loki/issues/852) is fixed, updating
Helm and Ksonnet configs needs to be done in a separate commit following
the release tag so that Helm tests pass.
1. Merge the changelog PR.
1. Create a new tag for the release.
1. Once this step is done, the CI will be triggered to create release
artifacts and publish them to a draft release. The tag will be made
publicly available immediately.
1. Run the following to create the tag:
```bash
RELEASE=v1.2.3 # UPDATE ME to reference new release
git checkout release-1.2.x # checkout release branch
git pull
git tag -s $RELEASE -m "tagging release $RELEASE"
git push origin $RELEASE
```
1. Watch Drone and wait for all the jobs to finish running.
## Updating Helm and Ksonnet configs
These steps should be executed after the previous section, once CircleCI has
finished running all the release jobs.
1. Run `bash ./tools/release_prepare.sh`
1. When prompted for the release version, enter the latest tag.
1. When prompted for new Helm version numbers, the defaults should suffice (a
minor version bump).
1. Commit the changes to a new branch, push, make a PR, and get it merged.
## Publishing the Release Draft
Once the previous two steps are completed, you can publish your draft!
1. Go to the [GitHub releases page](https://github.com/grafana/loki/releases)
and find the drafted release.
1. Edit the drafted release, copying and pasting *notable changes* from the
CHANGELOG. Add a link to the CHANGELOG, noting that the full list of changes
can be found there. Refer to other releases for help with formatting this.
1. Optionally, have other team members review the release draft so you feel
comfortable with it.
1. Publish the release!
## Versioning Loki docs on Grafana Website
Loki docs are versioned. Follow the below steps to version Loki docs for this release.
>NOTE: Here $LOCAL_LOKI_PATH is your local path where Loki is checked out with correct $VERSION
1. Clone Grafana website [repo](https://github.com/grafana/website)
1. Create new branch `git checkout -b $VERSION` (replace `$VERSION` with current release version. e.g: `v2.5.0`)
1. Run `mv content/docs/loki/next content/docs/loki/next.main`
1. Run `mkdir content/docs/loki/next`
1. Run `cp -R $LOCAL_LOKI_PATH/docs/sources/* content/docs/loki/next`
1. Run `scripts/docs-release.sh loki latest next`
1. Run `scripts/docs-release.sh loki $VERSION latest`
1. Run `mv content/docs/loki/next.main content/docs/loki/next`
1. Update `version_latest` to `$VERSION` in `content/docs/loki/_index.md`
1. Docs will be generated for this release.
1. Create PR and Merge it after approval.
docs/sources/community/maintaining/release/1-create-release-branch.md
+38
View File
@@ -0,0 +1,38 @@
---
title: Create Release Branch
description: Create Release Branch
---
# Create Release Branch
A single release branch is created for every `major` or `minor` release (not for patch releases). That release
branch is then used for all the Stable Releases, and all Patch Releases for that `major` and `minor` versions of the Grafana Loki.
## Before you begin
1. Determine the [VERSION_PREFIX]({{< relref "./concepts/version" >}}).
1. Announce about the upcoming release in `#loki-releases` internal slack channel.
1. Skip this announcement for a patch release. Create an issue to communicate beginning of the release process with the community. Example issue [here](https://github.com/grafana/loki/issues/10468).
## Steps
1. Determine which commit should be used as a base for the release branch. Usually this is a `kxx` weekly release branch.
1. Create and push the release branch from the selected base commit:
The name of the release branch should be `release-VERSION_PREFIX`, such as `release-2.9.x`.
{{% admonition type="note" %}}
Branches are only made for VERSION_PREFIX; do not create branches for the full VERSION such as `release-v2.9.1` or `release-2.9.1`.
{{% /admonition %}}
{{% admonition type="note" %}}
Don't create any other branches that are prefixed with `release` when creating PRs or those branches will collide with our automated release build publish rules.
{{% /admonition %}}
1. Create a label to make backporting PRs to this branch easy.
The name of the label should be `backport release-VERSION_PREFIX`, such as `backport release-2.9.x`.
{{% admonition type="note" %}}
Note there is space in the label name. The label name must follow this naming convention to trigger CI related jobs.
{{% /admonition %}}
docs/sources/community/maintaining/release/2-backport-commits.md
+30
View File
@@ -0,0 +1,30 @@
---
title: Backport commits
description: Backport commits
---
# Backport commits
Any PRs or commits not on the release branch that you want to include in the release must be backported to the release branch.
## Before you begin
1. Determine the [VERSION_PREFIX]({{< relref "./concepts/version" >}}).
2. If the release branch already has all the code changes on it, skip this step.
## Steps
1. Pick a PR that you want to backport to `release-VERSION_PREFIX` branch.
1. Add two labels to the PR. First, one of the `product-approved`, `type/doc` or `type/bug` appropriately. This is to make sure the PRs that are backported are done with right intention. Second `backport release-VERSION_PREFIX` label.
Now CI should automatically create backport PR to the correct release branch. Example [PR](https://github.com/grafana/loki/pull/10333)
{{% admonition type="note" %}}
CI automation can fail sometimes if there are some merge conflicts in cherry picking the commits. In those cases, the original PR where you added the label should have additional comment explaining how to backport it manually.
{{% /admonition %}}
{{% admonition type="note" %}}
The CI job that helps with backporting PR is `.github/workflows/backport.yml`. Useful for debugging purposes.
{{% /admonition %}}
1. Repeat the above steps for any PRs that need to be backported.
docs/sources/community/maintaining/release/3-prepare-release-notes.md
+48
View File
@@ -0,0 +1,48 @@
---
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
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).
docs/sources/community/maintaining/release/4-prepare-changelog.md
+33
View File
@@ -0,0 +1,33 @@
---
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).
docs/sources/community/maintaining/release/5-document-metrics-configurations-changes.md
+27
View File
@@ -0,0 +1,27 @@
---
title: Document metrics and configurations changes
description: Document metrics and configurations changes
---
# Document metrics and configurations changes
Any metrics and configurations that are removed or modified need to be documented in the upgrade guide. Configurations whose default values changed should also be documented in the upgrade guide.
## Before you begin
All the steps are performed on `release-VERSION_PREFIX` branch.
## Steps
1. Check which configs changed, including whose default values changed.
```
$ OLD_VERSION=X.Y.Z ./tools/diff-config.sh
```
1. Record configurations that are modified (either renamed or had its default value changed) in the [upgrade guide]({{< relref "./6-prepare-upgrade-guide" >}}).
1. Check if any metrics have changed.
```
$ OLD_VERSION=X.Y.Z ./tools/diff-metrics.sh
```
1. Record metrics whose names have been modified in the [upgrade guide]({{< relref "./6-prepare-upgrade-guide" >}}).
docs/sources/community/maintaining/release/6-prepare-upgrade-guide.md
+21
View File
@@ -0,0 +1,21 @@
---
title: Prepare Upgrade guide
description: Prepare Upgrade guide
---
# Prepare Upgrade guide
The upgrade guide records changes that require user attention or interaction to upgrade to specific Loki version from previous versions.
## Before you begin
The upgrade guide in Grafana Loki works as follows.
We have a `setup/upgrade/_index.md` file that records upgrade information for all Loki releases.
## Steps
1. Make sure the upgrade guide is up to date on the `release-VERSION_PREFIX` branch under the `Main/Unreleased` section.
1. On the `release-VERSION_PREFIX` branch promote `Main/Unreleased` to `VERSION`. 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)`.
docs/sources/community/maintaining/release/7-update-version-numbers.md
+29
View File
@@ -0,0 +1,29 @@
---
title: Update version numbers
description: Update version numbers
---
# Update version numbers
Upgrade the Loki version to the new release version in documents, examples, jsonnets, etc.
## Before you begin
1. Determine the [VERSION_PREFIX]({{< relref "./concepts/version" >}}).
2. Skip this step if you are doing a patch release on old release branch.
Example: Latest release branch is `release-2.9.x` but you are releasing patch version in `release-2.8.x` (or older)
## Steps
1. Upgrade the versions in the `release-VERSION_PREFIX` branch.
Example commands:
```
LOKI_NEW_VERSION=$VERSION ./tools/release_update_tags.sh
```
{{% admonition type="note" %}}
Do not upgrade the version numbers in the `operator/` directory as @periklis and team have a different process to upgrade the Operator version.
{{% /admonition %}}
docs/sources/community/maintaining/release/8-tag-release.md
+53
View File
@@ -0,0 +1,53 @@
---
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 "./3-prepare-release-notes" >}}) and [CHANGELOG.md]({{< relref "./4-prepare-changelog" >}}). All versions in the repo should have already been [updated]({{< relref "./7-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.
docs/sources/community/maintaining/release/9-publish-release.md
+28
View File
@@ -0,0 +1,28 @@
---
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 "./8-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!
docs/sources/community/maintaining/release/README.md
+33
View File
@@ -0,0 +1,33 @@
---
title: Releasing Grafana Loki
description: Releasing Grafana Loki
aliases:
- ../../maintaining/release/
---
# Releasing Grafana Loki
This document is a series of instructions for core Grafana Loki maintainers to be able
to publish a new [Grafana Loki](https://github.com/grafana/loki) release.
## Release stable version
1. [Create release branch]({{< relref "./1-create-release-branch" >}})
1. [Backport commits]({{< relref "./2-backport-commits" >}})
1. [Prepare Release notes]({{< relref "./3-prepare-release-notes" >}})
1. [Prepare Changelog]({{< relref "./4-prepare-changelog" >}})
1. [Document Metrics and Configurations changes]({{< relref "./5-document-metrics-configurations-changes" >}})
1. [Prepare Upgrade guide]({{< relref "./6-prepare-upgrade-guide" >}})
1. [Update version numbers]({{< relref "./7-update-version-numbers" >}})
1. [Tag Release]({{< relref "./8-tag-release" >}})
1. [Publish Release]({{< relref "./9-publish-release" >}})
## Release patched version
1. [Backport commits]({{< relref "./2-backport-commits" >}})
1. [Prepare Release notes]({{< relref "./3-prepare-release-notes" >}})
1. [Prepare Changelog]({{< relref "./4-prepare-changelog" >}})
1. [Document Metrics and Configurations changes]({{< relref "./5-document-metrics-configurations-changes" >}})
1. [Prepare Upgrade guide]({{< relref "./6-prepare-upgrade-guide" >}})
1. [Update version numbers]({{< relref "./7-update-version-numbers" >}})
1. [Tag Release]({{< relref "./8-tag-release" >}})
1. [Publish Release]({{< relref "./9-publish-release" >}})
docs/sources/community/maintaining/release/concepts/version.md
+25
View File
@@ -0,0 +1,25 @@
---
title: Version
description: Version
---
# Version
Grafana Loki uses Semantic Versioning. The next version can be determined
by looking at the current version and incrementing it. When the release is a new `major` version (for example, after 2.9.1 we decide to go 3.0.0 instead of 2.9.2) this should not be done.
You need to set two environmental values `VERSION` and `VERSION_PREFIX` to do the release process.
## Version
To determine the `VERSION` for a Stable Release or Patch Release, use the Semantic Version `A.B.C`.
- Examples
- For example, `2.9.0` is the Stable Release `VERSION` for the v2.9.0 release.
- For example, `2.9.1` is the first Patch Release `VERSION` for the v2.9.0 release.
## Version Prefix
To determine the `VERSION PREFIX`, use only the major and minor version `A.B.x`.
- Examples
- `2.9.x`
tools/release_update_tags.sh
Executable
+36
View File
@@ -0,0 +1,36 @@
#!/bin/bash
set -euo pipefail
OLD_VERSION=${LOKI_OLD_VERSION:-}
NEW_VERSION=${LOKI_NEW_VERSION:-}
if [[ -z "${OLD_VERSION}" ]]
then
OLD_VERSION="[0-9]+\.[0-9]+\.[0-9]+"
fi
if [[ -z "${NEW_VERSION}" ]]
then
read -rp "Enter new release version (eg 2.9.2): " NEW_VERSION
fi
LOKI_DOCKER_DRIVER_TAG="grafana\/loki-docker-driver:"
LOKI_DOCUMENTS_TAG="loki\/v"
LOKI_DOCKER_TAG="grafana\/loki:"
LOKI_PROMTAIL_DOCKER_TAG="grafana\/promtail:"
LOKI_CANARY_DOCKER_TAG="grafana\/loki-canary:"
LOKI_LOGCLI_DOCKER_TAG="grafana\/logcli:"
echo "Updating version references to ${NEW_VERSION}"
# grep -Iq is to ignore non-binary files.
find . -type f -not -path "./.git/*" -not -path "./vendor/*" -not -path "./operator/*" -not -path "./CHANGELOG.md" -not -path "./docs/sources/setup/upgrade/*" -exec grep -Iq . {} \; -print0\
| xargs -0 sed -i '' -E \
-e "s/(${LOKI_DOCKER_DRIVER_TAG})(${OLD_VERSION})/\1${NEW_VERSION}/g" \
-e "s/(${LOKI_DOCUMENTS_TAG})(${OLD_VERSION})/\1${NEW_VERSION}/g" \
-e "s/(${LOKI_DOCKER_TAG})(${OLD_VERSION})/\1${NEW_VERSION}/g" \
-e "s/(${LOKI_PROMTAIL_DOCKER_TAG})(${OLD_VERSION})/\1${NEW_VERSION}/g" \
-e "s/(${LOKI_CANARY_DOCKER_TAG})(${OLD_VERSION})/\1${NEW_VERSION}/g" \
-e "s/(${LOKI_LOGCLI_DOCKER_TAG})(${OLD_VERSION})/\1${NEW_VERSION}/g" \