IntenseWebs/opentofu
3
0
Fork 0
mirror of https://github.com/opentofu/opentofu.git synced 2024-12-28 01:41:48 -06:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #31550 from hashicorp/docs-readme-updates-versioned-docs

Browse Source 
Update Docs README to support versioned documentation
This commit is contained in:
Laura Pacilio 2022-08-02 14:08:02 -04:00 committed by GitHub
commit 38fe6f761d
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 22 additions and 4 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

26
website/README.md
View File

@ -17,6 +17,10 @@ Click **Edit this page** at the bottom of any Terraform website page to go direc
Updates to the sidebar navigation of Terraform docs need to be made in the [`terraform-website`](https://github.com/hashicorp/terraform-website/) repository (preferably in a PR also updating the submodule commit). You can read more about how to make modifications to the navigation in the [README for `terraform-website`](https://github.com/hashicorp/terraform-website#editing-navigation-sidebars).
## 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`](https://github.com/hashicorp/terraform-website/) repository, allowing you to preview the entire Terraform documentation site.
@ -41,8 +45,22 @@ You should preview all of your changes locally before creating a pull request. T
## Deploy Changes
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.
New commits in `hashicorp/terraform` do not automatically deploy the site. Do the following for documentation pull requests:
- **Add a backport label to the PR.** Use the label that corresponds to the latest Terraform patch release (e.g., `1.2-backport`). When you merge your PR to `main`, GitHub bot automatically generates a backport PR to merge your commits into the appropriate release branch.
- **Merge the backport PR.** When all tests pass successfully, merge the backport PR into the release branch. The new content will be added to the site during the next minor release.
- **Cherry-pick changes to `stable-website`.** If you want your changes to show up immediately, check out the latest version of the`stable-website` branch, cherry-pick your changes to the branch, and run `git push`. Your changes will be live on the site within the hour.
Merging a PR to `main` queues up documentation changes for the next minor product release. To update the latest documentation, you must also backport your changes to one or more release branches. Changes that you push to a release branch become live on the site within one hour.
For example, if Terraform is on v1.2.x:
- Merge to `main`: Documentation for v1.3 features.
- Merge to `main` and backport to `v1.2` release branch: Typo fixes, page restructures, documentation to support v1.2 patch releases, etc.
### 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. For example, if Terraform is currently on v1.2 and you need to add a security warning to the v1.1 documentation, you can backport (cherry-pick) commits to the v1.1 branch by labeling the PR with a backport label (e.g., 1.2-backport) associated with the release branch for the target version.
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. Someone needs to manually merge the backport PR to finish backporting the changes.
If the changes in the backport pull request are effectively equivalent to the original, you can review and merge your own backport pull request without waiting for another review. 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.