From 208edb51142bdc177ffbbc10add595c544fa8894 Mon Sep 17 00:00:00 2001 From: Kevin Wang Date: Fri, 22 Jul 2022 11:25:48 -0400 Subject: [PATCH 1/2] chore: reame and contributing --- .github/CONTRIBUTING.md | 12 +++++++++++- website/README.md | 42 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 53 insertions(+), 1 deletion(-) create mode 100644 website/README.md diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 6992e928cd..b44595aa65 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -50,7 +50,7 @@ or submitting a patch. ## New Issue -We welcome issues of all kinds including feature requests, bug reports or documentation suggestions. Below are guidelines for well-formed issues of each type. +We welcome issues of all kinds including feature requests, bug reports or documentation contributions. Below are guidelines for well-formed issues of each type. ### Bug Reports @@ -67,6 +67,16 @@ It is possible we already fixed the bug you're experiencing. - [ ] **Include a use case description**: In addition to describing the behavior of the feature you'd like to see added, it's helpful to also lay out the reason why the feature would be important and how it would benefit the wider Terraform ecosystem. Use case in context of 1 provider is good, wider context of more providers is better. +### Documentation Contributions + + - [ ] **Search for possible duplicate suggestions**: It's helpful to keep + suggestions consolidated to one thread, so do a quick search on existing + @@ -81,6 +81,8 @@ type. + "how do servers' schemas get merged?" in mind. This helps us ensure the + documentation is targeted, specific, and framed in a useful way. + + - [ ] **Contribute**: This repository contains the markdown files that generate versioned documentation for [terraform.io/plugin/sdkv2](https://www.terraform.io/plugin/sdkv2). Please open a pull request with documentation changes. Refer to the [website README](../website/README.md) for more information. + ## New Pull Request Thank you for contributing! diff --git a/website/README.md b/website/README.md new file mode 100644 index 0000000000..e25f491afd --- /dev/null +++ b/website/README.md @@ -0,0 +1,42 @@ +# Terraform Documentation + +This directory contains the portions of [the Terraform website][terraform.io] that pertain to the Terraform Plugin SDK. + +The files in this directory are intended to be used in conjunction with +[the `terraform-website` repository](https://github.com/hashicorp/terraform-website), which brings all of the +different documentation sources together and contains the scripts for testing and building the site as +a whole. + +## Updating Sidebar Navigation + +You must update the sidebar navigation for the `terraform-plugin-sdk` documentation any time that you add or delete a documentation page. The website builds the sidebar navigation menu from the [nav-data] JSON file. For more details about how to update this file, refer to 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 your changes locally to ensure that the content is rendering properly before you create 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. + +To preview your content, complete the following steps: + +**Set Up Local Environment** + +1. [Install Docker](https://docs.docker.com/get-docker/). +1. Restart your terminal or command line session. + +**Launch Site Locally** + +1. Navigate into your local `terraform-plugin-sdk` top-level directory and run `make website`. +1. Open `http://localhost:3000` in your web browser. While the preview is running, you can edit pages and Next.js will automatically rebuild them. +1. When you're done with the preview, press `ctrl-C` in your terminal to stop the server. + +## Deployment + +The website reads content from release tags to generate documentation for all versions of `terraform-plugin-sdk` documentation. Changes merged into `main` will be included in the documentation for the next product release. + +You cannot edit documentation for past versions of `terraform-plugin-sdk` on the site. Documentation is an artifact of a product release. We push docs fixes forward for the next release, rather than retroactively fixing older versions. + +[nav-data]: ../website/data/plugin-sdk-nav-data.json +[terraform.io]: https://www.terraform.io/ \ No newline at end of file From 2ad51570d5177496384c48828b1ef6b5737ea81f Mon Sep 17 00:00:00 2001 From: Brian Flad Date: Fri, 22 Jul 2022 12:19:51 -0400 Subject: [PATCH 2/2] Update .github/CONTRIBUTING.md --- .github/CONTRIBUTING.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index b44595aa65..bcc05a5de3 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -71,8 +71,12 @@ It is possible we already fixed the bug you're experiencing. - [ ] **Search for possible duplicate suggestions**: It's helpful to keep suggestions consolidated to one thread, so do a quick search on existing - @@ -81,6 +81,8 @@ type. - "how do servers' schemas get merged?" in mind. This helps us ensure the + issues to check if anybody else has suggested the same thing. You can scope + searches by the label `documentation` to help narrow things down. + + - [ ] **Describe the questions you're hoping the documentation will answer**: + It's very helpful when writing documentation to have specific questions like + "how do I implement a default value?" in mind. This helps us ensure the documentation is targeted, specific, and framed in a useful way. - [ ] **Contribute**: This repository contains the markdown files that generate versioned documentation for [terraform.io/plugin/sdkv2](https://www.terraform.io/plugin/sdkv2). Please open a pull request with documentation changes. Refer to the [website README](../website/README.md) for more information.