The okteto cli adheres to the semver versioning scheme as defined by the spec. Whenever a new change needs to be released it is up to the team to decide the type of change based on the following guidelines:
Reserved for big changes in functionality and/or API breaking changes. Having a major release means that there’s something different about how the cli or okteto works that might break existing functionality.
This type of release is usually accompanied by a blog post and or new documentation.
Reserved for new functionality and backward-compatible changes. If deemed relevant, a new blog post explaining what’s new should accompany the new release as well as new documentation.
Patch releases are reserved for bug fixes and security fixes. Upgrading from an existing version to a new patch should not be a breaking change and the upgrade should always work.
Major and minor releases may have intermediate releases that are released earlier to a subset of users (mostly the okteto team). These are pre-releases that extend the releases above but are intended mostly for testing. We’ll go into detail about this below.
The okteto cli is released through three channels:
-
Stable - Version Format: 1.2.3
Fully supported stable releases and ready for use by external users.
-
Beta - Version Format: 1.2.3-beta.1
Pre-releases that are pretty stable but intended mostly for testing and advanced users. A beta release eventually becomes a stable release. Beta releases are created for minor and major releases (1.2.3-beta.1). Patch releases are meant to be bug fixes and hence stable enough.
-
Dev - Version Format: git SHA (short)
These are releases that are not guaranteed to be stable and should be used internally and/or for testing purposes. Dev releases are built nightly from the master branch. These releases don't follow the semver versioning scheme and git tags are not created for them. They could eventually be promoted although there is no guarantee that changes made in this release will make it to a more stable channel.
The okteto cli is available to install from the following installation methods:
-
Direct Download
Okteto is a static binary that can be directly downloaded from our downloads page:
# replace stable with (beta or dev) for other channels curl -fSL https://downloads.okteto.com/cli/stable/okteto-$(uname)-$(uname -m) -o ./okteto chmod +x ./okteto mv -f ./okteto /usr/local/bin
You could also download and install a specific version:
https://downloads.okteto.com/cli/stable/2.2.2/okteto-$(uname)-$(uname -m)
-
Script
This is the script available at https://get.okteto.com.
Usually installed like this (Mac and Linux):
curl https://get.okteto.com -sSfL | shThis is effectively using the direct download above to install the latest binary from the stable release. Currently, this method only supports the stable channel.
If, for whatever reason, a different versions is needed you can set the OKTETO_VERSION environment variable:
curl https://get.okteto.com -sSfL | OKTETO_VERSION=2.2.2 shAlthough the install script command is safe to run, we advise users to first inspect its contents to understand what we are executing under the hood.
-
Brew
homebrew is a package manager for macOS and Linux:
brew install okteto
Only the stable channel is supported for this installation method.
New versions might take up to 2 days to become available since it requires the homebrew team to review and update them manually.
-
Scoop
Scoop is a command-line installer for windows:
scoop install okteto
Only the stable channel is supported for this installation method:
Okteto CLI releases are created by CircleCI and saved as Github Releases. Each release in Github maps to a release that can be downloaded through our stable channels. Github pre-releases map to beta releases.
All new releases (including pre-releases) are accompanied by the appropriate release notes that describe all the changes in detail since the previous release of the same channel.
Release notes are autogenerated by CI and saved in the Github Release description.
Upon creating a release, the following artifacts are uploaded to https://downloads.okteto.com/cli/<version>/<name>:
- okteto-Darwin-arm64
- okteto-Darwin-arm64.sha256
- okteto-Darwin-x86_64
- okteto-Darwin-x86_64.sha256
- okteto-Linux-arm64
- okteto-Linux-arm64.sha256
- okteto-Linux-x86_64
- okteto-Linux-x86_64.sha256
- okteto.exe
- okteto.exe.sha256
For eg: https://downloads.okteto.com/cli/2.2.2/okteto-Darwin-x86_64
The same artifacts are also uploaded to the Github release assets and can be downloaded from there.
Alongside the release artifacts, a docker image is automatically created for each release and pushed to hub.docker.com/r/okteto/okteto:
docker pull okteto/okteto:2.2.2To be able to properly generate the release notes, all PRs must have the appropriate labels based on the scope of the change. One of the following labels must be applied to Pull Requests:
If a Pull Request does not have one of these labels checks will fail and PR merging will be blocked.
Work is done on master. Not directly of course, but rather Pull Requests are opened against the master branch.
Nightly, a CI job runs and creates a dev release, for eg: dev-220601 (June 1st, 2022). These releases automatically become available to install from the direct download explained above
Once it is decided to create a new release, a new release-MAJOR.MINOR should be created.
Upon creating this new branch, a new release candidate will be created for that version eg: 2.4.0-beta.1. Subsequent commits to the release branch will keep bumping the prerelease to beta.2, beta.3, etc. New patch releases in released branches should be created manually by creating and pushing the tag. Stable releases are not automatically created.
Stable releases are only created from release branches. This is, promoting a beta release from the release branch by simply tagging the HEAD of that branch.
---*----------*----------*----------*----------*----------*----------> master
\
0---------------0---------------0---------------1---------------> release-2.4 (manually created)
\ \ \ \
2.4.0.beta.1 2.4.0.beta.2 2.4.0.beta.3 2.4.1.beta.1
2.4.0 (manual)
To recap, the human/manual intervention for releasing is:
- When you are ready to create a release candidate for a minor or major version, simply create a
release-MAJOR.MINORbranch and push it. This will automatically create the first release candidate in the beta channel and will become available to download - To create a new release candidate simply open PRs against a release branch. Once merged it will be automatically created
Releasing a stable version is a manual process and should be done from the release-MAJOR.MINOR branch always. It is simply re-tagging (promoting) the latest beta version into the stable versions.
$ git fetch --tags
$ git checkout release-2.4
$ git pull origin release-2.4
$ git log --oneline -n 5 --abbrev-commit
# 32a3cf31 (HEAD -> release-2.4, tag: 2.4.3-beta.1, origin/release-2.4) Fix github actions latest release (#2906) (#2907)
# abaf67e5 (tag: 2.4.2-beta.2, tag: 2.4.2) fix configmap filename file path (#2864) (#2900)
# 96dd8ea0 (tag: 2.4.2-beta.1) fix github actions release script (#2865)
# 8db8f6de (tag: 2.4.1-beta.5, tag: 2.4.1) Handle jobs "completed" status properly for the "--wait" flag (#2862) (#2863)
# 1cbda7c5 (tag: 2.4.1-beta.4) Run windows tests in staging (#2784) (#2859)
$ git tag 2.4.3 2.4.3-beta.1
$ git push origin 2.4.3In this case we are promoting 2.4.3-beta.1 which points to 32a3cf31 to be the 2.4.3 stable release. Both tags SHOULD point to the same commit.
Once the tag is pushed it will be automatically built and released by circleci
Backporting fixes should be done by cherry-picking commits (when possible) and opening pull requests against the release branches. Once merged, a prerelease will be created for the patch (for eg1.2.3-beta.4) for testing purposes. As explained above, to create the patch release, tag the release branch, and push it.