CONTRIBUTING.RELEASE.md
[!WARNING] This manual is intended for OpenTofu core and fork maintainers. If you are looking for the normal contribution guide, see this file.
This manual describes how to create an OpenTofu release. OpenTofu has two kinds of releases. Alpha and Beta releases are created
from the main branch, while we split off a version (e.g. v1.8) branch before creating an rc or stable
release.
X.Y.0-alphaW, where X,Y and W are numbers, such as 1.2.0-alpha1.X.Y.0-betaW, where X,Y and W are numbers, such as 1.2.0-beta1.X.Y.0-rcW, where X,Y and W are numbers, such as 1.2.0-rc1.X.Y.0, where X and Y are numbers, such as 1.2.0.X.Y.Z where X, Y and Z are numbers, such as 1.2.3.[!WARNING] Many tools depend on the release order on GitHub to determine the latest version. When creating a point release, make sure to release the oldest version first, then follow by the newer versions. Do not release an older point release without also releasing the newer versions or tooling will break.
To create a release, make sure you have people on standby with the following credentials:
Before you start creating a release, make sure you have the following marketing collaterals ready to be published:
<details><summary>X.Y.0-alphaW)X.Y.0-betaW)X.Y.0-rcW)X.Y.0)X.Y.Z)Before you can create a release, you need to make sure the following files are up to date:
(unreleased) string from the version number before the stable release.)Ideally, make sure these changes go in as the last PR before the release.
Now that you have the files up to date, do the following:
main for alpha and beta releasesvX.Y for any other releases (assuming you are releasing version X.Y.Z)git pullgit tag -m "X.Y.Z" vX.Y.Z (assuming you are releasing version X.Y.Z)
-s option to create a GPG-signed taggit push origin vX.Y.ZNow comes the big step, creating the actual release.
release workflow on the left sideRun workflow button, which opens a popup menualpha releases, select the main branchvX.Y.ZX.Y version, check the Release as latest? option.alpha, beta or rc version, check the Release as prerelease? option.Run workflow button.Now the release process will commence and create a draft release on GitHub. If you did not check the prerelease option, it will also publish to Snapcraft and PackageCloud.
The release process takes about 30 minutes. When it is complete, head over to the Releases section of the main repository and find the new draft release. Change the following settings
Set as a pre-release if you are releasing an alpha, beta, or release candidate.Set as the latest release if you are releasing a stable or point release for the latest major version. Do not check this checkbox if you are releasing a point release for an older major version.Create a discussion for this release if you are releasing a stable (X.Y.0) version.Publish releaseCreate a text highlighting how users can test the new features, for example:
⚠️ Do not use this release for production workloads! ⚠️
It's time for the first prerelease of the 1.9.0 version! This includes a lot of major and minor new features, as well as a ton of community contributions!
The highlights are:
* **`for_each` in provider configuration blocks:** An alternate (aka "aliased") provider configuration can now have multiple dynamically-chosen instances using the `for_each` argument:
```hcl
provider "aws" {
alias = "by_region"
for_each = var.aws_regions
region = each.key
}
```
Each instance of a resource can also potentially select a different instance of the associated provider configuration, making it easier to declare infrastructure that ought to be duplicated for each region.
X.Y.0)Create a more elaborate text explaining the flagship features of this release, ideally linking to the blog post and/or video for the release, for example:
We're proud to announce that OpenTofu 1.8.0 is now officially out! 🎉
## What's New?
* Early variable/locals evaluation
* Provider mocking in `tofu test`
* Resource overrides in `tofu test`
* Override files for OpenTofu: keeping compatibility
* Deprecation: `use_legacy_workflow` has been removed from the S3 backend-backend
See the launch post on our blog: https://opentofu.org/blog/opentofu-1-8-0/
For all the features, see the [detailed changelog](https://github.com/opentofu/opentofu/blob/v1.8.0/CHANGELOG.md).
You can find the full diff [here](https://github.com/opentofu/opentofu/compare/v1.7..v1.8.0).
X.Y.Z)For point releases, simply copy the section from the CHANGELOG.md file.
</details>get.opentofu.orgIn order for the installer script to work, you will need to update the https://get.opentofu.org/tofu/api.json file. You can do this by logging in to Cloudflare and go to the opentofu-get project in Cloudflare Pages. Here click the three dots on the latest production deployment and click Retry deployment.
Depending on the release type, you will need to update the opentofu.org repository.
Before you begin, make sure that all submodules are up to date by running:
git submodule init
git submodule update
<details> <summary>[!WARNING] If you are using Windows, make sure your system supports symlinks by enabling developer mode and enabling symlinks in git.
In .github/workflows/govulncheck.yml, there is a matrix with the actively maintained versions of OpenTofu. When the new branch for the stable version is created, update the matrix above by adding the new branch and removing the deprecated version.
X.Y.Z-alphaW), Beta (X.Y.Z-betaW) and Release Candidate (X.Y.Z-rcW)We do not release documentation for non-stable releases. There is no action needed beyond publishing the blog post.
</details> <details><summary>X.Y.0)git submodule add -b vX.Y https://github.com/opentofu/opentofu opentofu-repo/vX.Y
docusaurus.config.ts file and presets section."vX.Y-1": {
label: "X.Y-1.x",
path: "",
},
"vX.Y-1": {
label: "X.Y-1.x",
path: "vX.Y-1",
banner: "none",
},
"vX.Y": {
label: "X.Y.x",
path: "",
},
lastVersion option to point to your version. banner: "none",
navbar option and Docs dropdown to reflect the new version list. It should look something like this:
items: [
{
label: "vX.Y.x (current)",
href: "/docs/"
},
{
label: "vX.Y-1.x",
href: "/docs/vX.Y-1/"
},
// ...
{
label: "Development",
href: "/docs/main/"
},
],
X.Y.Z)For a point release, you merely need to make sure that the submodules for the supported versions are up to date. You can do this by running the following script:
cd opentofu-repo
for ver in $(ls); do
cd "${ver}"
git pull origin "${ver}"
cd ..
git add "${ver}"
done
Now you can commit your changes and open a pull request.
</details>Note: You can safely run the script above anytime you need to update the documentation independently of a release. It's ok for the website to have minor doc fixes that are not in line with OpenTofu releases.
Make sure you have a Linux box with Snapcraft installed and download the installer shell script from https://get.opentofu.org/install-opentofu.sh.
Now test the following 3 installation methods to make sure all distribution points are up to date.
sudo snap install opentofu --classictofu --versionsudo snap uninstall opentofu./install-opentofu.sh --install-method debtofu --versionapt remove --purge tofu./install-opentofu.sh --install-method standalone --opentofu-version X.Y.Z/usr/local/bin/tofu --versionsudo rm -rf /opt/opentofu /usr/local/bin/tofuOnce you are happy that the release works, post the announcements to the following places: