f260ed1177
We originally included this warning because the go-cty-yaml module wasn't yet stable and it was also not extensively tested so it wasn't yet clear if its behavior would need to change in some less common cases we hadn't tested so far. However, go-cty-yaml had its v1.0.0 release some time ago and is now committed to preserving its current Marshal output unless it is found to be non-compliant with the YAML 1.2 specification. This doc change means that Terraform's yamlencode is now adopting a similar posture: - The exact style details produced by the function for a particular input are now frozen. It'll change only if we find that the function is producing output that isn't valid per the YAML spec. - If someone finds a YAML parser that cannot parse what yamlencode produces but what it produces is valid per the YAML 1.2 spec, we'll expect the parser to be corrected to better support the spec rather than changing the yamlencode output. There may be pragmatic exceptions if we encounter a situation we cannot anticipate yet, but the above will be our general rule. This is really just a specialization of the spirit of the v1.x Compatibility Promises, tailored specifically to this function. |
||
|---|---|---|
| .. | ||
| data | ||
| docs | ||
| img/docs | ||
| layouts | ||
| scripts | ||
| package-lock.json | ||
| package.json | ||
| README.md | ||
| vercel.json | ||
Terraform Documentation
This directory contains the portions of the Terraform website that pertain to the core functionality, excluding providers and the overall configuration.
The website uses the files in this directory in conjunction with
the terraform-website repository. The terraform-website repository brings all of the documentation together and contains the scripts for testing and building the entire site.
Suggesting Changes
You can submit an issue with documentation requests or submit a pull request with suggested changes.
Click Edit this page at the bottom of any Terraform website page to go directly to the associated markdown file in GitHub.
Modifying Sidebar Navigation
You must update the the sidebar navigation when you add or delete documentation .mdx files. If you do not update the navigation, the website deploy preview fails.
To update the sidebar navigation, you must edit the appropriate nav-data.json file. This repository contains the sidebar navigation files for the following documentation sets:
- Terraform Language:
language-nav-data.json - Terraform CLI:
cli-nav-data.json - Introduction to Terraform:
intro-nav-data.json
For more details about how to update the sidebar navigation, refer to Editing Navigation Sidebars in the terraform-website repository.
Adding Redirects
You must add a redirect when you move, rename, or delete documentation pages. Refer to https://github.com/hashicorp/terraform-website#redirects for details.
Previewing Changes
You should preview all of your changes locally before creating a pull request. The build includes content from this repository and the terraform-website repository, allowing you to preview the entire Terraform documentation site.
Set Up Local Environment
-
Install Go or create a
~/godirectory manually. -
Open terminal and set
GOPATHas an environment variable:Bash:
export $GOPATH=~/go(bash)Zsh:
echo -n 'export GOPATH=~/go' >> ~/.zshrc -
Restart your terminal or command line session.
Launch Site Locally
- Navigate into your local
terraformtop-level directory and runmake website. - Open
http://localhost:3000in your web browser. While the preview is running, you can edit pages and Next.js automatically rebuilds them. - Press
ctrl-Cin your terminal to stop the server and end the preview.
Deploying Changes
Merging a PR to main queues up documentation changes for the next minor product release. Your changes are not immediately available on the website.
The website generates versioned documentation by pointing to the HEAD of the release branch for that version. For example, the v1.2.x documentation on the website points to the HEAD of the v1.2 release branch in the terraform repository. To update existing documentation versions, you must also backport your changes to that release branch. Backported changes become live on the site within one hour.
Backporting
Important: Editing old versions (not latest) should be rare. We backport to old versions when there is an egregious error. Egregious errors include inaccuracies that could cause security vulnerabilities or extreme inconvenience for users.
Backporting involves cherry-picking commits to one or more release branches within a docs repository. You can backport (cherry-pick) commits to a version branch by adding the associated backport label to your pull request. For example, if you need to add a security warning to the v1.1 documentation, you must add the 1.1-backport label. When you merge a pull request with one or more backport labels, GitHub Actions opens a backport PR to cherry-pick your changes to the associated release branches. You must manually merge the backport PR to finish backporting the changes.
To make your changes available on the latest docs version:
-
Add the backport label for the latest version.
-
Merge the pull request. GitHub Actions autogenerates a backport pull request, linked to the original.
-
Merge the auto-generated backport pull request.
You can review and merge your own backport pull request without waiting for another review if the changes in the backport pull request are effectively equivalent to the original. You can make minor adjustments to resolve merge conflicts, but you should not merge a backport PR that contains major content or functionality changes from the original, approved pull request. If you are not sure whether it is okay to merge a backport pull request, post a comment on the original pull request to discuss with the team.