opentofu/CONTRIBUTING.RELEASE.md

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.

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.

---

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

---

Preparing the repository for a release

Before you can create a release, you need to make sure the following files are up to date:

• CHANGELOG.md (Note: do not remove the (unreleased) string from the version number before the stable release.)
• version/VERSION

Ideally, make sure these changes go in as the last PR before the release.

---

Tagging the release

Now that you have the files up to date, do the following:

1. On your computer, make sure you have checked out the correct branch:
   • main for alpha and beta releases
   • vX.Y for any other releases (assuming you are releasing version X.Y.Z)
2. Make sure the branch is up-to-date by running git pull
3. Create the correct tag: git tag -m "X.Y.Z" vX.Y.Z (assuming you are releasing version X.Y.Z)
   • If you have a GPG key, consider adding the -s option to create a GPG-signed tag
4. Push the tag: git push origin vX.Y.Z

---

Creating the release

Now comes the big step, creating the actual release.

1. Head on over to the Actions tab on the main repository
2. Select the release workflow on the left side
3. Click the Run workflow button, which opens a popup menu
4. Select the correct branch:
   • For alpha releases, select the main branch
   • For all other releases, select the appropriate version branch
5. Enter the correct git tag name: vX.Y.Z
6. If you are releasing the latest X.Y version, check the Release as latest? option.
7. If you are releasing an alpha, beta or rc version, check the Release as prerelease? option.
8. Click the 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.

---

Publishing the GitHub release

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

• Edit the text (see the examples below).
• Check Set as a pre-release if you are releasing an alpha, beta, or release candidate.
• Check 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.
• Check Create a discussion for this release if you are releasing a stable (X.Y.0) version.
• Click Publish release

Alpha, beta, or release candidate

Create 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.

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:

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 file.

---

Updating get.opentofu.org

In 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.

---

Updating the website/documentation

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

Warning

If you are using Windows, make sure your system supports symlinks by enabling developer mode and enabling symlinks in git.

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 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:

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.

---

Testing the release

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.

1. Snapcraft (stable and point releases only):
   • sudo snap install opentofu --classic
   • tofu --version
   • sudo snap uninstall opentofu
2. Deb (stable and point releases only)
   • ./install-opentofu.sh --install-method deb
   • tofu --version
   • apt remove --purge tofu
3. Standalone:
   • ./install-opentofu.sh --install-method standalone --opentofu-version X.Y.Z
   • /usr/local/bin/tofu --version
   • sudo rm -rf /opt/opentofu /usr/local/bin/tofu

---

Posting the announcement

Once you are happy that the release works, post the announcements to the following places:

• Alpha: Community Slack, Linkedin, X, Blog, YouTube
• Beta: Community Slack, Linkedin, X, Blog
• Stable: Community Slack, Linkedin, X, Blog
• Point release: Community Slack