# OpenTofu release manual
> [!WARNING]
> This manual is intended for OpenTofu core and fork maintainers. If you are looking for the normal contribution guide, see [this file](CONTRIBUTING.md).
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.
---
## Naming in this document
- **Alpha** is an early preview release. This is versioned `X.Y.0-alphaW`, where `X`,`Y` and `W` are numbers, such as `1.2.0-alpha1`.
- **Beta** is a semi-stable preview release. This is versioned `X.Y.0-betaW`, where `X`,`Y` and `W` are numbers, such as `1.2.0-beta1`.
- **RC** is a release candidate which does not have new features over a beta. This is versioned `X.Y.0-rcW`, where `X`,`Y` and `W` are numbers, such as `1.2.0-rc1`.
- **Stable** is a release that has no new features and bug fixes over an RC. This is versioned `X.Y.0`, where `X` and `Y` are numbers, such as `1.2.0`.
- **Point release** is a release that contains bugfixes only on top of a stable release. This is versioned `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.
---
## Gathering the team for a release
To create a release, make sure you have people on standby with the following credentials:
- Cloudflare
- PackageCloud
- Snapcraft
- Linkedin
- X
---
## Preparing public relations collaterals for a release
Before you start creating a release, make sure you have the following marketing collaterals ready to be published:
### Alpha version (`X.Y.0-alphaW`)
- Feature Preview video for upcoming flagship features (see https://www.youtube.com/@opentofu for examples)
- "Help us test..." blog post (see https://opentofu.org/blog/ for examples)
- Community Slack announcement
- Linkedin and X posts
### Beta (`X.Y.0-betaW`)
- "Get ready for..." blog post (see https://opentofu.org/blog/ for examples)
- Community Slack announcement
- Linkedin and X posts
### Release Candidate (`X.Y.0-rcW`)
- Community Slack announcement
- Linkedin and X posts
### Stable release (`X.Y.0`)
- Release blog post with the feature and community highlights since the last release (see https://opentofu.org/blog/ for examples)
- Community Slack announcement
- Linkedin and X posts
### Point release (`X.Y.Z`)
- Community Slack announcement
### Alpha, beta, or release candidate
Create a text highlighting how users can test the new features, for example:
```markdown
⚠️ 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.
```
### Stable release (`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:
```markdown
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).
```
### Point release (`X.Y.Z`)
For point releases, simply copy the section from the [CHANGELOG.md](CHANGELOG.md) file.
## Updating govulncheck github workflow (only for stable releases)
In [.github/workflows/govulncheck.yml](.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.
### Alpha (`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.
### Stable (`X.Y.0`)
1. Add a submodule for the new release to the website repository:
```
git submodule add -b vX.Y https://github.com/opentofu/opentofu opentofu-repo/vX.Y
```
2. After you have done this, open the [`docusaurus.config.ts`](https://github.com/opentofu/opentofu.org/blob/main/docusaurus.config.ts) file and `presets` section.
3. Here, locate the previous latest version:
```
"vX.Y-1": {
label: "X.Y-1.x",
path: "",
},
```
Change it to:
```
"vX.Y-1": {
label: "X.Y-1.x",
path: "vX.Y-1",
banner: "none",
},
```
4. Now add the new version you are releasing:
```
"vX.Y": {
label: "X.Y.x",
path: "",
},
```
5. After this is set, change the `lastVersion` option to point to your version.
6. Now locate any version that is no longer supported and remove the following line to add a deprecation warning:
```
banner: "none",
```
7. Finally, locate the `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/"
},
],
```
### Point release (`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:
```bash
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.
> **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.