2021-04-07 12:39:16 +02:00
---
2023-10-13 13:54:33 +02:00
sort: 30
weight: 30
2023-04-30 12:31:45 +02:00
title: Release process guidance
menu:
docs:
2023-10-13 13:54:33 +02:00
parent: 'victoriametrics'
weight: 30
2023-04-30 12:31:45 +02:00
aliases:
- /Release-Guide.html
2021-04-07 12:39:16 +02:00
---
# Release process guidance
2019-12-05 18:28:21 +01:00
2023-05-10 09:50:41 +02:00
## Pre-reqs
2022-08-31 01:27:24 +02:00
1. Make sure you have enterprise remote configured
```
git remote add enterprise < url >
```
2023-07-26 23:08:19 +02:00
1. Make sure you have singing key configured
1. Make sure you have github token with at least `read:org, repo, write:packages` permissions exported under `GITHUB_TOKEN` env variable.
2022-08-31 01:27:24 +02:00
You can create token [here ](https://github.com/settings/tokens )
2023-07-26 23:08:19 +02:00
1. Make sure you're [authorized ](https://hub.docker.com/orgs/victoriametrics/settings/enforce-sign-in/windows ) for pushing docker images
2022-08-31 01:27:24 +02:00
2023-06-13 10:37:51 +02:00
### For MacOS users
Make sure you have GNU version of utilities `zip` , `tar` , `sha256sum` . To install them run the following commands:
2024-01-27 19:29:11 +01:00
```sh
2023-06-13 10:37:51 +02:00
brew install coreutils
brew install gnu-tar
export PATH="/usr/local/opt/coreutils/libexec/gnubin:$PATH"
```
Docker may need additional configuration changes:
2024-01-27 19:29:11 +01:00
```sh
2023-06-13 10:37:51 +02:00
docker buildx create --use --name=qemu
docker buildx inspect --bootstrap
```
By default, docker on MacOS has limited amount of resources (CPU, mem) to use.
Bumping the limits may significantly improve build speed.
2019-12-05 18:28:21 +01:00
## Release version and Docker images
2023-08-11 13:29:04 +02:00
1. Make sure all the changes are documented in [CHANGELOG.md ](https://github.com/VictoriaMetrics/VictoriaMetrics/blob/master/docs/CHANGELOG.md ).
Ideally, every change must be documented in the commit with the change. Alternatively, the change must be documented immediately
after the commit, which adds the change.
2024-06-03 10:04:13 +02:00
1. Make sure all the changes are synced between `master` , `cluster` , `enterprise-single-node` and `enterprise-cluster` branches.
2024-04-16 09:48:52 +02:00
Changes in these branches must be synced immediately after they are committed in at least a single branch.
2023-08-11 13:29:04 +02:00
1. Make sure that the release branches have no security issues.
1. Update release versions if needed in [SECURITY.md ](https://github.com/VictoriaMetrics/VictoriaMetrics/blob/master/SECURITY.md ).
2023-07-26 23:08:19 +02:00
1. Add `(available starting from v1.xx.y)` line to feature docs introduced in the upcoming release.
1. Cut new version in [CHANGELOG.md ](https://github.com/VictoriaMetrics/VictoriaMetrics/blob/master/docs/CHANGELOG.md )
2023-08-11 13:29:04 +02:00
and make it merged. See example in this [commit ](https://github.com/VictoriaMetrics/VictoriaMetrics/commit/b771152039d23b5ccd637a23ea748bc44a9511a7 ).
2024-03-01 01:51:41 +01:00
1. Cherry-pick bug fixes relevant for [LTS releases ](https://docs.victoriametrics.com/lts-releases/ ).
2023-07-26 23:08:19 +02:00
1. Make sure you get all changes fetched `git fetch --all` .
1. Create the following release tags:
2022-01-31 18:18:48 +01:00
* `git tag -s v1.xx.y` in `master` branch
* `git tag -s v1.xx.y-cluster` in `cluster` branch
2023-08-11 13:29:04 +02:00
* `git tag -s v1.xx.y-enterprise` in `enterprise-single-node` branch
2022-01-31 18:18:48 +01:00
* `git tag -s v1.xx.y-enterprise-cluster` in `enterprise-cluster` branch
2023-07-26 23:08:19 +02:00
1. Run `TAG=v1.xx.y make publish-release` . This command performs the following tasks:
2022-08-31 01:27:24 +02:00
a) Build and package binaries in `*.tar.gz` release archives with the corresponding `_checksums.txt` files inside `bin` directory.
This step can be run manually with the command `make release` from the needed git tag.
b) Build and publish [multi-platform Docker images ](https://docs.docker.com/build/buildx/multiplatform-images/ )
for the given `TAG` , `TAG-cluster` , `TAG-enterprise` and `TAG-enterprise-cluster` .
The multi-platform Docker image is built for the following platforms:
* linux/amd64
* linux/arm64
* linux/arm
* linux/ppc64le
* linux/386
This step can be run manually with the command `make publish` from the needed git tag.
2023-07-28 11:44:31 +02:00
1. Push the tags `v1.xx.y` and `v1.xx.y-cluster` created at step 8 to public GitHub repository at https://github.com/VictoriaMetrics/VictoriaMetrics.
2023-07-20 01:55:10 +02:00
Push the tags `v1.xx.y` , `v1.xx.y-cluster` , `v1.xx.y-enterprise` and `v1.xx.y-enterprise-cluster` to the corresponding
branches in private repository.
2023-05-10 09:50:41 +02:00
**Important note:** do not push enterprise tags to public GitHub repository - they must be pushed only to private repository.
2023-07-26 23:08:19 +02:00
1. Run `TAG=v1.xx.y make github-create-release github-upload-assets` . This command performs the following tasks:
2022-09-08 13:51:17 +02:00
a) Create draft GitHub release with the name `TAG` . This step can be run manually
2022-08-31 01:27:24 +02:00
with the command `TAG=v1.xx.y make github-create-release` .
The release id is stored at `/tmp/vm-github-release` file.
2023-07-28 11:44:31 +02:00
b) Upload all the binaries and checksums created at step `9a` to that release.
2022-08-31 01:27:24 +02:00
This step can be run manually with the command `make github-upload-assets` .
It is expected that the needed release id is stored at `/tmp/vm-github-release` file,
2022-09-08 13:51:17 +02:00
which must be created at the step `a` .
2022-08-31 01:27:24 +02:00
If the upload process is interrupted by any reason, then the following recovery steps must be performed:
- To delete the created draft release by running the command `make github-delete-release` .
This command expects that the id of the release to delete is located at `/tmp/vm-github-release`
2022-09-08 13:51:17 +02:00
file created at the step `a` .
2022-08-31 01:27:24 +02:00
- To run the command `TAG=v1.xx.y make github-create-release github-upload-assets` , so new release is created
and all the needed assets are re-uploaded to it.
2023-07-26 23:08:19 +02:00
1. Go to < https: // github . com / VictoriaMetrics / VictoriaMetrics / releases > and verify that draft release with the name `TAG` has been created
2022-08-31 01:27:24 +02:00
and this release contains all the needed binaries and checksums.
2023-07-26 23:08:19 +02:00
1. Update the release description with the content of [CHANGELOG ](https://github.com/VictoriaMetrics/VictoriaMetrics/blob/master/docs/CHANGELOG.md ) for this release.
1. Publish release by pressing "Publish release" green button in GitHub's UI.
1. Bump version of the VictoriaMetrics cluster in the [sandbox environment ](https://github.com/VictoriaMetrics/ops/blob/main/gcp-test/sandbox/manifests/benchmark-vm/vmcluster.yaml )
2022-08-31 01:27:24 +02:00
by [opening and merging PR ](https://github.com/VictoriaMetrics/ops/pull/58 ).
2023-07-26 23:08:19 +02:00
1. Bump VictoriaMetrics version at `deployment/docker/docker-compose.yml` and at `deployment/docker/docker-compose-cluster.yml` .
2023-07-31 14:05:17 +02:00
1. Follow the instructions in [release follow-up ](https://github.com/VictoriaMetrics/VictoriaMetrics-enterprise/blob/master/Release-Guide.md ).
2019-12-05 18:28:21 +01:00
2022-03-22 12:40:55 +01:00
### Public Announcement
2020-12-19 20:58:03 +01:00
2022-03-22 12:40:55 +01:00
* Publish message in Slack at < https: // victoriametrics . slack . com >
* Post at Twitter at < https: // twitter . com / MetricsVictoria >
* Post in Reddit at < https: // www . reddit . com / r / VictoriaMetrics />
2023-05-10 09:50:41 +02:00
* Post in LinkedIn at < https: // www . linkedin . com / company / victoriametrics />
2022-03-22 12:40:55 +01:00
* Publish message in Telegram at < https: // t . me / VictoriaMetrics_en > and < https: // t . me / VictoriaMetrics_ru1 >
2023-05-10 09:50:41 +02:00
* Publish message in Google Groups at < https: // groups . google . com / forum /#! forum / victorametrics-users >
2019-12-05 18:28:21 +01:00
2023-09-11 09:55:30 +02:00
## Operator
The operator repository [https://github.com/VictoriaMetrics/operator/ ](https://github.com/VictoriaMetrics/operator/ )
### Bump the version of images
- Bump `Version` field in [file `internal/config/config.go` ](https://github.com/VictoriaMetrics/operator/blob/master/internal/config/config.go ) with new release version for:
- `vmalert` in `BaseOperatorConf.VMAlertDefault.Version` ,
- `vmagent` in `BaseOperatorConf.VMAgentDefault.Version` ,
- `vmsingle` in `BaseOperatorConf.VMSingleDefault.Version` ,
- `vmselect` in `BaseOperatorConf.VMClusterDefault.VMSelectDefault.Version` ,
- `vmstorage` in `BaseOperatorConf.VMClusterDefault.VMStorageDefault.Version` ,
- `vminsert` in `BaseOperatorConf.VMClusterDefault.VMInsertDefault.Version` ,
- `vmbackupmanager` in `BaseOperatorConf.VMBackup.Version` (should be enterprise version),
- `vmauth` in `BaseOperatorConf.VMAuthDefault.Version` .
- Run `make operator-conf` .
2023-11-15 21:55:45 +01:00
- Rename "Next release" section in `docs/CHANGELOG.md` to the *new release version* and create new empty "Next release" section.
2023-09-11 09:55:30 +02:00
- Commit and push changes to `master` .
- Create and push a new tag with the *new release version* .
2023-11-15 21:55:45 +01:00
- Create github release from this tag with "Release notes" from `docs/CHANGELOG.md` for this version in description.
2023-09-11 09:55:30 +02:00
2019-12-05 18:28:21 +01:00
## Helm Charts
The helm chart repository [https://github.com/VictoriaMetrics/helm-charts/ ](https://github.com/VictoriaMetrics/helm-charts/ )
2022-03-22 12:40:55 +01:00
### Bump the version of images
2019-12-05 18:28:21 +01:00
2023-06-13 10:37:51 +02:00
Bump `tag` field in `values.yaml` with new release version.
Bump `appVersion` field in `Chart.yaml` with new release version.
2023-09-11 09:55:30 +02:00
Add new line to "Next release" section in `CHANGELOG.md` about version update (the line must always start with "`-`"). Do **NOT** change headers in `CHANGELOG.md` .
Bump `version` field in `Chart.yaml` with incremental semver version (based on the `CHANGELOG.md` analysis).
2023-06-13 10:37:51 +02:00
Do these updates to the following charts:
2022-04-04 11:14:27 +02:00
1. Update `vmagent` chart version in [`values.yaml` ](https://github.com/VictoriaMetrics/helm-charts/blob/master/charts/victoria-metrics-agent/values.yaml ) and [`Chart.yaml` ](https://github.com/VictoriaMetrics/helm-charts/blob/master/charts/victoria-metrics-agent/Chart.yaml )
2023-07-26 23:08:19 +02:00
1. Update `vmalert` chart version in [`values.yaml` ](https://github.com/VictoriaMetrics/helm-charts/blob/master/charts/victoria-metrics-alert/values.yaml ) and [`Chart.yaml` ](https://github.com/VictoriaMetrics/helm-charts/blob/master/charts/victoria-metrics-alert/Chart.yaml )
1. Update `vmauth` chart version in [`values.yaml` ](https://github.com/VictoriaMetrics/helm-charts/blob/master/charts/victoria-metrics-auth/values.yaml ) and [`Chart.yaml` ](https://github.com/VictoriaMetrics/helm-charts/blob/master/charts/victoria-metrics-auth/Chart.yaml )
1. Update `cluster` chart versions in [`values.yaml` ](https://github.com/VictoriaMetrics/helm-charts/blob/master/charts/victoria-metrics-cluster/values.yaml ), bump version for `vmselect` , `vminsert` and `vmstorage` and [`Chart.yaml` ](https://github.com/VictoriaMetrics/helm-charts/blob/master/charts/victoria-metrics-cluster/Chart.yaml )
1. Update `k8s-stack` chart versions in [`values.yaml` ](https://github.com/VictoriaMetrics/helm-charts/blob/master/charts/victoria-metrics-k8s-stack/values.yaml ), bump version for `vmselect` , `vminsert` , `vmstorage` , `vmsingle` , `vmalert` , `vmagent` and [`Chart.yaml` ](https://github.com/VictoriaMetrics/helm-charts/blob/master/charts/victoria-metrics-k8s-stack/Chart.yaml )
1. Update `single-node` chart version in [`values.yaml` ](https://github.com/VictoriaMetrics/helm-charts/blob/master/charts/victoria-metrics-single/values.yaml ) and [`Chart.yaml` ](https://github.com/VictoriaMetrics/helm-charts/blob/master/charts/victoria-metrics-single/Chart.yaml )
2023-10-14 07:46:00 +02:00
1. Update `vmgateway` chart version in [`values.yaml` ](https://github.com/VictoriaMetrics/helm-charts/blob/master/charts/victoria-metrics-gateway/values.yaml ) and [`Chart.yaml` ](https://github.com/VictoriaMetrics/helm-charts/blob/master/charts/victoria-metrics-gateway/Chart.yaml )
2023-06-13 10:37:51 +02:00
Once updated, run the following commands:
2023-09-11 09:55:30 +02:00
1. Commit and push changes to `master` .
1. Run "Release" action on Github:
2024-01-26 19:01:20 +01:00
< img src = "Release-Guide_helm-release.webp" alt = "release helm charts" >
2023-09-11 09:55:30 +02:00
1. Merge new PRs *"Automatic update CHANGELOGs and READMEs"* and *"Synchronize docs"* after pipelines are complete.
2019-12-05 18:28:21 +01:00
2022-04-04 11:14:27 +02:00
## Ansible Roles
2022-03-22 12:40:55 +01:00
2022-04-04 11:14:27 +02:00
### Bump the version of images
2019-12-05 18:28:21 +01:00
2022-04-04 11:14:27 +02:00
Repository [https://github.com/VictoriaMetrics/ansible-playbooks ](https://github.com/VictoriaMetrics/ansible-playbooks )
2019-12-05 18:28:21 +01:00
2022-04-04 11:14:27 +02:00
1. Update `vmagent` version in [`main.yml` ](https://github.com/VictoriaMetrics/ansible-playbooks/blob/master/roles/vmagent/defaults/main.yml#L4 )
2023-07-26 23:08:19 +02:00
1. Update `vmalert` version in [`main.yml` ](https://github.com/VictoriaMetrics/ansible-playbooks/blob/master/roles/vmalert/defaults/main.yml#L4 )
1. Update `cluster` version in [`main.yml` ](https://github.com/VictoriaMetrics/ansible-playbooks/blob/master/roles/cluster/defaults/main.yml#L3 )
1. Update `single` version in [`main.yml` ](https://github.com/VictoriaMetrics/ansible-playbooks/blob/master/roles/single/defaults/main.yml#L6 )
1. Commit changes
1. Create a new tag
1. Create a new release. This automatically publishes the new versions to galaxy.ansible.com
2023-01-04 14:36:14 +01:00
## RPM packages
2024-02-27 12:08:11 +01:00
### Bump the version of components
2023-01-04 14:36:14 +01:00
2023-01-10 10:14:56 +01:00
Repository [https://github.com/VictoriaMetrics/victoriametrics-lts-rpm ](https://github.com/VictoriaMetrics/victoriametrics-lts-rpm )
2023-01-04 14:36:14 +01:00
1. Update `vmagent` version in [`vmagent.spec` ](https://github.com/VictoriaMetrics/victoriametrics-lts-rpm/blob/master/vmagent.spec#L2 )
2023-07-26 23:08:19 +02:00
1. Update `vmalert` version in [`vmalert.spec` ](https://github.com/VictoriaMetrics/victoriametrics-lts-rpm/blob/master/vmalert.spec#L2 )
1. Update `vmauth` version in [`vmauth.spec` ](https://github.com/VictoriaMetrics/victoriametrics-lts-rpm/blob/master/vmauth.spec#L2 )
1. Update `vmbackup` version in [`vmbackup.spec` ](https://github.com/VictoriaMetrics/victoriametrics-lts-rpm/blob/master/vmbackup.spec#L2 )
1. Update `vmctl` version in [`vmctl.spec` ](https://github.com/VictoriaMetrics/victoriametrics-lts-rpm/blob/master/vmctl.spec#L2 )
1. Update `vmrestore` version in [`vmrestore.spec` ](https://github.com/VictoriaMetrics/victoriametrics-lts-rpm/blob/master/vmrestore.spec#L2 )
1. Update `vminsert` version in [`vminsert.spec` ](https://github.com/VictoriaMetrics/victoriametrics-lts-rpm/blob/master/vminsert.spec#L2 )
1. Update `vmselect` version in [`vmselect.spec` ](https://github.com/VictoriaMetrics/victoriametrics-lts-rpm/blob/master/vmselect.spec#L2 )
1. Update `vmstorage` version in [`vmstorage.spec` ](https://github.com/VictoriaMetrics/victoriametrics-lts-rpm/blob/master/vmstorage.spec#L2 )
1. Update `vmsingle` version in [`vmsingle.spec` ](https://github.com/VictoriaMetrics/victoriametrics-lts-rpm/blob/master/vmsingle.spec#L2 )
1. Commit and push changes to the repository. This will automatically build and publish new versions of RPM packages.