From c434db158e631b0bfddb92e1dd342b924880f29a Mon Sep 17 00:00:00 2001 From: Petros Kolyvas Date: Fri, 27 Mar 2020 10:08:59 -0400 Subject: [PATCH 01/23] Codeowners initial update --- CODEOWNERS | 19 ++++++++++++++----- 1 file changed, 14 insertions(+), 5 deletions(-) diff --git a/CODEOWNERS b/CODEOWNERS index 34e9ec7668..16a1271b3a 100644 --- a/CODEOWNERS +++ b/CODEOWNERS @@ -1,8 +1,17 @@ # Each line is a file pattern followed by one or more owners. # More on CODEOWNERS files: https://help.github.com/en/github/creating-cloning-and-archiving-repositories/about-code-owners -# Remote-state backends -/backend/remote-state/azure @hashicorp/terraform-azure -/backend/remote-state/gcs @hashicorp/terraform-google -/backend/remote-state/s3 @hashicorp/terraform-aws -/backend/remote-state/cos @likexian +# Remote-state backend +/backend/remote-state/artifactory Unmaintained +/backend/remote-state/azure @hashicorp/terraform-azure +/backend/remote-state/consul @hashicorp/consul +/backend/remote-state/cos @likexian +/backend/remote-state/etcdv2 Unmaintained +/backend/remote-state/etcdv2 Unmaintained +/backend/remote-state/gcs @hashicorp/terraform-google +/backend/remote-state/http Unmaintained +/backend/remote-state/manta Unmaintained +/backend/remote-state/oss @xiaozhu36 +/backend/remote-state/pg Unmaintained +/backend/remote-state/s3 @hashicorp/terraform-aws +/backend/remote-state/swift Unmaintained \ No newline at end of file From a40207c9eb85f89a79b98007f779a06fe1890b4b Mon Sep 17 00:00:00 2001 From: Petros Kolyvas Date: Fri, 27 Mar 2020 11:13:28 -0400 Subject: [PATCH 02/23] Updated contributing to Terraform --- .github/CONTRIBUTING.md | 279 +++++++++++++--------------------------- 1 file changed, 92 insertions(+), 187 deletions(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 5fde5a7b7c..52f8555ecd 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -1,111 +1,114 @@ -# Contributing to Terraform +# Contributing to Terraform ---- +------ -This repository contains only Terraform core, which includes the command line -interface and the main graph engine. Providers are implemented as plugins that -each have their own repository in -[the `terraform-providers` organization](https://github.com/terraform-providers) -on GitHub. Instructions for developing each provider are in the associated -README file. For more information, see -[the provider development overview](https://www.terraform.io/docs/plugins/provider.html). +This repository contains only Terraform core, which includes the command line interface and the main graph engine. Providers are implemented as plugins that each have their own repository in [the `terraform-providers` organization](https://github.com/terraform-providers) on GitHub. Instructions for developing each provider are in the associated README file. For more information, see [the provider development overview](https://www.terraform.io/docs/plugins/provider.html). ---- +---- -Terraform is an open source project and we appreciate contributions of various -kinds, including bug reports and fixes, enhancement proposals, documentation -updates, and user experience feedback. +**First:** if you're unsure or afraid of *anything*, just ask or submit the issue anyway. You won't be yelled at for giving your best effort. The worst that can happen is that you'll be politely asked to change something or move . We appreciate any sort of contributions, and don't want a wall of rules to get in the way of that. -To record a bug report, enhancement proposal, or give any other product -feedback, please [open a GitHub issue](https://github.com/hashicorp/terraform/issues/new/choose) -using the most appropriate issue template. Please do fill in all of the -information the issue templates request, because we've seen from experience that -this will maximize the chance that we'll be able to act on your feedback. +However, for those individuals who want a bit more guidance on the best way to contribute to this project, read on. This document will cover what we're looking for in order to help set some expectations and help you get the most out of participation in this project. -Please note that we _don't_ use GitHub issues for usage questions. If you have -a question about how to use Terraform in general or how to solve a specific -problem with Terraform, please start a topic in -[the Terraform community forum](https://discuss.hashicorp.com/c/terraform-core), -where both Terraform team members and community members participate in -discussions. +Terraform is managed by small core development team and so we aren't always able to respond to every issue or pull request in a timely manner. -**All communication on GitHub, the community forum, and other HashiCorp-provided -communication channels is subject to -[the HashiCorp community guidelines](https://www.hashicorp.com/community-guidelines).** +To record a bug report, enhancement proposal, or give any other product feedback, please [open a GitHub issue](https://github.com/hashicorp/terraform/issues/new/choose) using the most appropriate issue template. Please do fill in all of the information the issue templates request, because we've seen from experience that this will maximize the chance that we'll be able to act on your feedback. + +## Proposing a Change + +In order to be respectful of the time of community contributors, we prefer to discuss potential changes in GitHub issues prior to implementation. That will allow us to give design feedback up front and set expectations about the scope of the change, and, for larger changes, how best to approach the work such that the Terraform team can review it and merge it along with other concurrent work. + +If the bug you wish to fix or enhancement you wish to implement isn't already covered by a GitHub issue that contains feedback from the Terraform team, please do start a discussion (either in [a new GitHub issue](https://github.com/hashicorp/terraform/issues/new/choose) or an existing one, as appropriate) before you invest significant development time. If you mention your intent to implement the change described in your issue, the Terraform team can prioritize including implementation-related feedback in the subsequent discussion. + +At this time, we do not have a formal process for reviewing outside proposals that significantly change Terraform's workflow, its primary usage patterns, and its language. While we do hope to put such a thing in place in the future, we wish to be up front with potential contributors that unfortunately we are unlikely to be able to give prompt feedback for large proposals that could entail a significant design phase, though we are still interested to hear about your use-cases so that we can consider ways to meet them as part of other larger projects. + +Most changes will involve updates to the test suite, and changes to Terraform's documentation. The Terraform team can advise on different testing strategies for specific scenarios, and may ask you to revise the specific phrasing of your proposed documentation prose to match better with the standard "voice" of Terraform's documentation. + +This repository is primarily maintained by a small team at HashiCorp along with their other responsibilities, so unfortunately we cannot always respond promptly to pull requests, particularly if they do not relate to an existing GitHub issue where the Terraform team has already participated. We *are* grateful for all contributions however, and will give feedback on pull requests as soon as we're able. + +### Caveats + +#### State Storage Backends + +The Terraform team is not merging PRs for new state storage backends. Our current priority regarding state storage backends is to find maintainers for existing backends and work towards removal of those without maintainership. + +Please see the CODEOWNERS file for the status of a given backend. + +The Terraform team will not be merging new state storage backends at this time. The burden it places on a team to setup an environment and cloud service provider account, or a new database/storage/key-value service, in order to build and test remote state storage prevents us from moving Terraform forward in other ways. + +We are working to remove ourselves from the critical path of state storage backends. Unfortuanately in the mean time, we won't be accepting new backends. + +### Pull Request Lifecycle + +1. You are welcome to submit your pull request for commentary or review before it is fully completed. Please prefix the title of your pull request with "[WIP]" to indicate this. It's also a good idea to include specific questions or items you'd like feedback on. +2. Once you believe your pull request is ready to be merged, you can remove any "[WIP]" prefix from the title and a core team member will review. +3. When time permits Terraform's core team members will look over your contribution and either merge, or provide comments letting you know if there is anything left to do. It may take some time for us to respond. We may also have questions that we need answered about the code, either because something doesn't make sense to us or because we want to understand your thought process. We'd kindly ask that you do not target specific team members. +4. If we have requested changes, you can either make those changes or, if you disagree with the suggested changes, we can have a conversation about our reasoning and agree on a path forward. This may be a multi-step process. Our view is that pull requests are a chance to collaborate, and we welcome conversations about how to do things better. It is the contributor's responsibility to address any changes requested. While reviewers are happy to give guidance, it is unsustainable for us to perform the coding work necessary to get a PR into a mergeable state. +5. Once all outstanding comments and checklist items have been addressed, your contribution will be merged! Merged PRs may or may not be included in the next release based on changes the Terraform teams deems as breaking or not. The core team takes care of updating the [CHANGELOG.md](https://github.com/hashicorp/terraform/blob/master/CHANGELOG.md) as they merge. +6. In some cases, we might decide that a PR should be closed without merging. We'll make sure to provide clear reasoning when this happens. Following the above + +#### Getting Your Pull Requests Merged Faster + +It is much easier to review pull requests that are: + +1. Well-documented: Try to explain in the pull request comments what your change does, why you have made the change, and provide instructions for how to produce the new behavior introduced in the pull request. If you can, provide screen captures or terminal output to show what the changes look like. This helps the reviewers understand and test the change. +2. Small: Try to only make one change per pull request. If you found two bugs and want to fix them both, that's *awesome*, but it's still best to submit the fixes as separate pull requests. This makes it much easier for reviewers to keep in their heads all of the implications of individual code changes, and that means the PR takes less effort and energy to merge. In general, the smaller the pull request, the sooner reviewers will be able to make time to review it. +3. Passing Tests: Based on how much time we have, we may not review pull requests which aren't passing our tests. (Look below for advice on how to run unit tests). If you need help figuring out why tests are failing, please feel free to ask, but while we're happy to give guidance it is generally your responsibility to make sure that tests are passing. If your pull request changes an interface or invalidates an assumption that causes a bunch of tests to fail, then you need to fix those tests before we can merge your PR. + +If we request changes, try to make those changes in a timely manner. Otherwise, PRs can go stale and be a lot more work for all of us to merge in the future. + +Even with everyone making their best effort to be responsive, it can be time-consuming to get a PR merged. It can be frustrating to deal with the back-and-forth as we make sure that we understand the changes fully. Please bear with us, and please know that we appreciate the time and energy you put into the project. + +### PR Checks + +The following checks run when a PR is opened: + +- Contributor License Agreement (CLA): If this is your first contribution to Terraform you will be asked to sign the CLA. +- Tests: tests include unit tests and acceptance tests, and all tests must pass before a PR can be merged. +- Test Coverage Report: We use [codecov](https://codecov.io/) to check both overall test coverage, and patch coverage. + +-> **Note:** We are still deciding on the right targets for our code coverage check. A failure in `codecov` does not necessarily mean that your PR will not be approved or merged. ## Terraform CLI/Core Development Environment -This repository contains the source code for Terraform CLI, which is the main -component of Terraform that contains the core Terraform engine. +This repository contains the source code for Terraform CLI, which is the main component of Terraform that contains the core Terraform engine. -The HashiCorp-maintained Terraform providers are also open source but are not -in this repository; instead, they are each in their own repository in -[the `terraform-providers` organization](https://github.com/terraform-providers) -on GitHub. +The HashiCorp-maintained Terraform providers are also open source but are not in this repository; instead, they are each in their own repository in [the `terraform-providers` organization](https://github.com/terraform-providers) on GitHub. -This repository also does not include the source code for some other parts of -the Terraform product including Terraform Cloud, Terraform Enterprise, and the -Terraform Registry. Those components are not open source, though if you have -feedback about them (including bug reports) please do feel free to -[open a GitHub issue on this repository](https://github.com/hashicorp/terraform/issues/new/choose). +This repository also does not include the source code for some other parts of the Terraform product including Terraform Cloud, Terraform Enterprise, and the Terraform Registry. Those components are not open source, though if you have feedback about them (including bug reports) please do feel free to [open a GitHub issue on this repository](https://github.com/hashicorp/terraform/issues/new/choose). ---- +------ -If you wish to work on the Terraform CLI source code, you'll first need to -install the [Go](https://golang.org/) compiler and the version control system -[Git](https://git-scm.com/). +If you wish to work on the Terraform CLI source code, you'll first need to install the [Go](https://golang.org/) compiler and the version control system [Git](https://git-scm.com/). -At this time the Terraform development environment is targeting only Linux and -Mac OS X systems. While Terraform itself is compatible with Windows, -unfortunately the unit test suite currently contains Unix-specific assumptions -around maximum path lengths, path separators, etc. +At this time the Terraform development environment is targeting only Linux and Mac OS X systems. While Terraform itself is compatible with Windows, unfortunately the unit test suite currently contains Unix-specific assumptions around maximum path lengths, path separators, etc. -Refer to the file [`.go-version`](.go-version) to see which version of Go -Terraform is currently built with. Other versions will often work, but if you -run into any build or testing problems please try with the specific Go version -indicated. You can optionally simplify the installation of multiple specific -versions of Go on your system by installing -[`goenv`](https://github.com/syndbg/goenv), which reads `.go-version` and -automatically selects the correct Go version. +Refer to the file [`.go-version`](https://github.com/hashicorp/terraform/blob/master/.github/.go-version) to see which version of Go Terraform is currently built with. Other versions will often work, but if you run into any build or testing problems please try with the specific Go version indicated. You can optionally simplify the installation of multiple specific versions of Go on your system by installing [`goenv`](https://github.com/syndbg/goenv), which reads `.go-version` and automatically selects the correct Go version. -Use Git to clone this repository into a location of your choice. Terraform is -using [Go Modules](https://blog.golang.org/using-go-modules), and so you -should _not_ clone it inside your `GOPATH`. +Use Git to clone this repository into a location of your choice. Terraform is using [Go Modules](https://blog.golang.org/using-go-modules), and so you should *not* clone it inside your `GOPATH`. -Switch into the root directory of the cloned repository and build Terraform -using the Go toolchain in the standard way: +Switch into the root directory of the cloned repository and build Terraform using the Go toolchain in the standard way: ``` cd terraform go install . ``` -The first time you run the `go install` command, the Go toolchain will download -any library dependencies that you don't already have in your Go modules cache. -Subsequent builds will be faster because these dependencies will already be -available on your local disk. +The first time you run the `go install` command, the Go toolchain will download any library dependencies that you don't already have in your Go modules cache. Subsequent builds will be faster because these dependencies will already be available on your local disk. -Once the compilation process succeeds, you can find a `terraform` executable in -the Go executable directory. If you haven't overridden it with the `GOBIN` -environment variable, the executable directory is the `bin` directory inside -the directory returned by the following command: +Once the compilation process succeeds, you can find a `terraform` executable in the Go executable directory. If you haven't overridden it with the `GOBIN` environment variable, the executable directory is the `bin` directory inside the directory returned by the following command: ``` go env GOPATH ``` -If you are planning to make changes to the Terraform source code, you should -run the unit test suite before you start to make sure everything is initially -passing: +If you are planning to make changes to the Terraform source code, you should run the unit test suite before you start to make sure everything is initially passing: ``` go test ./... ``` -As you make your changes, you can re-run the above command to ensure that the -tests are _still_ passing. If you are working only on a specific Go package, -you can speed up your testing cycle by testing only that single package, or -packages under a particular package prefix: +As you make your changes, you can re-run the above command to ensure that the tests are *still* passing. If you are working only on a specific Go package, you can speed up your testing cycle by testing only that single package, or packages under a particular package prefix: ``` go test ./command/... @@ -114,53 +117,29 @@ go test ./addrs ## Acceptance Tests: Testing interactions with external services -Terraform's unit test suite is self-contained, using mocks and local files -to help ensure that it can run offline and is unlikely to be broken by changes -to outside systems. +Terraform's unit test suite is self-contained, using mocks and local files to help ensure that it can run offline and is unlikely to be broken by changes to outside systems. -However, several Terraform components interact with external services, such -as the automatic provider installation mechanism, the Terraform Registry, -Terraform Cloud, etc. +However, several Terraform components interact with external services, such as the automatic provider installation mechanism, the Terraform Registry, Terraform Cloud, etc. -There are some optional tests in the Terraform CLI codebase that _do_ interact -with external services, which we collectively refer to as "acceptance tests". -You can enable these by setting the environment variable `TF_ACC=1` when -running the tests. We recommend focusing only on the specific package you -are working on when enabling acceptance tests, both because it can help the -test run to complete faster and because you are less likely to encounter -failures due to drift in systems unrelated to your current goal: +There are some optional tests in the Terraform CLI codebase that *do* interact with external services, which we collectively refer to as "acceptance tests". You can enable these by setting the environment variable `TF_ACC=1` when running the tests. We recommend focusing only on the specific package you are working on when enabling acceptance tests, both because it can help the test run to complete faster and because you are less likely to encounter failures due to drift in systems unrelated to your current goal: ``` TF_ACC=1 go test ./internal/initwd ``` -Because the acceptance tests depend on services outside of the Terraform -codebase, and because the acceptance tests are usually used only when making -changes to the systems they cover, it is common and expected that drift in -those external systems will cause test failures. Because of this, prior to -working on a system covered by acceptance tests it's important to run the -existing tests for that system in an _unchanged_ work tree first and respond -to any test failures that preexist, to avoid misinterpreting such failures as -bugs in your new changes. +Because the acceptance tests depend on services outside of the Terraform codebase, and because the acceptance tests are usually used only when making changes to the systems they cover, it is common and expected that drift in those external systems will cause test failures. Because of this, prior to working on a system covered by acceptance tests it's important to run the existing tests for that system in an *unchanged* work tree first and respond to any test failures that preexist, to avoid misinterpreting such failures as bugs in your new changes. ## Generated Code -Some files in the Terraform CLI codebase are generated. In most cases, we -update these using `go generate`, which is the standard way to encapsulate -code generation steps in a Go codebase. +Some files in the Terraform CLI codebase are generated. In most cases, we update these using `go generate`, which is the standard way to encapsulate code generation steps in a Go codebase. ``` go generate ./... ``` -Use `git diff` afterwards to inspect the changes and ensure that they are what -you expected. +Use `git diff` afterwards to inspect the changes and ensure that they are what you expected. -Terraform includes generated Go stub code for the Terraform provider plugin -protocol, which is defined using Protocol Buffers. Because the Protocol Buffers -tools are not written in Go and thus cannot be automatically installed using -`go get`, we follow a different process for generating these, which requires -that you've already installed a suitable version of `protoc`: +Terraform includes generated Go stub code for the Terraform provider plugin protocol, which is defined using Protocol Buffers. Because the Protocol Buffers tools are not written in Go and thus cannot be automatically installed using `go get`, we follow a different process for generating these, which requires that you've already installed a suitable version of `protoc`: ``` make protobuf @@ -168,113 +147,39 @@ make protobuf ## External Dependencies -Terraform uses Go Modules for dependency management, but currently uses -"vendoring" to include copies of all of the external library dependencies -in the Terraform repository to allow builds to complete even if third-party -dependency sources are unavailable. +Terraform uses Go Modules for dependency management, but currently uses "vendoring" to include copies of all of the external library dependencies in the Terraform repository to allow builds to complete even if third-party dependency sources are unavailable. -Our dependency licensing policy for Terraform excludes proprietary licenses -and "copyleft"-style licenses. We accept the common Mozilla Public License v2, -MIT License, and BSD licenses. We will consider other open source licenses -in similar spirit to those three, but if you plan to include such a dependency -in a contribution we'd recommend opening a GitHub issue first to discuss what -you intend to implement and what dependencies it will require so that the -Terraform team can review the relevant licenses to for whether they meet our -licensing needs. +Our dependency licensing policy for Terraform excludes proprietary licenses and "copyleft"-style licenses. We accept the common Mozilla Public License v2, MIT License, and BSD licenses. We will consider other open source licenses in similar spirit to those three, but if you plan to include such a dependency in a contribution we'd recommend opening a GitHub issue first to discuss what you intend to implement and what dependencies it will require so that the Terraform team can review the relevant licenses to for whether they meet our licensing needs. -If you need to add a new dependency to Terraform or update the selected version -for an existing one, use `go get` from the root of the Terraform repository -as follows: +If you need to add a new dependency to Terraform or update the selected version for an existing one, use `go get` from the root of the Terraform repository as follows: ``` go get github.com/hashicorp/hcl/v2@2.0.0 ``` -This command will download the requested version (2.0.0 in the above example) -and record that version selection in the `go.mod` file. It will also record -checksums for the module in the `go.sum`. +This command will download the requested version (2.0.0 in the above example) and record that version selection in the `go.mod` file. It will also record checksums for the module in the `go.sum`. -To complete the dependency change, clean up any redundancy in the module -metadata files and resynchronize the `vendor` directory with the new package -selections by running the following commands: +To complete the dependency change, clean up any redundancy in the module metadata files and resynchronize the `vendor` directory with the new package selections by running the following commands: ``` go mod tidy go mod vendor ``` -To ensure that the vendoring has worked correctly, be sure to run the unit -test suite at least once in _vendoring_ mode, where Go will use the vendored -dependencies to build the test programs: +To ensure that the vendoring has worked correctly, be sure to run the unit test suite at least once in *vendoring* mode, where Go will use the vendored dependencies to build the test programs: ``` go test -mod=vendor ./... ``` -Because dependency changes affect a shared, top-level file, they are more likely -than some other change types to become conflicted with other proposed changes -during the code review process. For that reason, and to make dependency changes -more visible in the change history, we prefer to record dependency changes as -separate commits that include only the results of the above commands and the -minimal set of changes to Terraform's own code for compatibility with the -new version: +Because dependency changes affect a shared, top-level file, they are more likely than some other change types to become conflicted with other proposed changes during the code review process. For that reason, and to make dependency changes more visible in the change history, we prefer to record dependency changes as separate commits that include only the results of the above commands and the minimal set of changes to Terraform's own code for compatibility with the new version: ``` git add go.mod go.sum vendor git commit -m "vendor: go get github.com/hashicorp/hcl/v2@2.0.0" ``` -You can then make use of the new or updated dependency in new code added in -subsequent commits. +You can then make use of the new or updated dependency in new code added in subsequent commits. -## Proposing a Change +#### -If you'd like to contribute a code change to Terraform, we'd love to review -a GitHub pull request. - -In order to be respectful of the time of community contributors, we prefer to -discuss potential changes in GitHub issues prior to implementation. That will -allow us to give design feedback up front and set expectations about the scope -of the change, and, for larger changes, how best to approach the work such that -the Terraform team can review it and merge it along with other concurrent work. - -If the bug you wish to fix or enhancement you wish to implement isn't already -covered by a GitHub issue that contains feedback from the Terraform team, -please do start a discussion (either in -[a new GitHub issue](https://github.com/hashicorp/terraform/issues/new/choose) -or an existing one, as appropriate) before you invest significant development -time. If you mention your intent to implement the change described in your -issue, the Terraform team can prioritize including implementation-related -feedback in the subsequent discussion. - -At this time, we do not have a formal process for reviewing outside proposals -that significantly change Terraform's workflow, its primary usage patterns, -and its language. While we do hope to put such a thing in place in the future, -we wish to be up front with potential contributors that unfortunately we are -unlikely to be able to give prompt feedback for large proposals that could -entail a significant design phase, though we are still interested to hear about -your use-cases so that we can consider ways to meet them as part of other -larger projects. - -Most changes will involve updates to the test suite, and changes to Terraform's -documentation. The Terraform team can advise on different testing strategies -for specific scenarios, and may ask you to revise the specific phrasing of -your proposed documentation prose to match better with the standard "voice" of -Terraform's documentation. - -This repository is primarily maintained by a small team at HashiCorp along with -their other responsibilities, so unfortunately we cannot always respond -promptly to pull requests, particularly if they do not relate to an existing -GitHub issue where the Terraform team has already participated. We _are_ -grateful for all contributions however, and will give feedback on pull requests -as soon as we're able. - -### PR Checks - -The following checks run when a PR is opened: - -* Contributor License Agreement (CLA): If this is your first contribution to Terraform you will be asked to sign the CLA. -* Tests: tests include unit tests and acceptance tests, and all tests must pass before a PR can be merged. -* Test Coverage Report: We use [codecov](https://codecov.io/) to check both overall test coverage, and patch coverage. - --> **Note:** We are still deciding on the right targets for our code coverage check. A failure in `codecov` does not necessarily mean that your PR will not be approved or merged. From 236b108cd8fd27247c24bf71bf3b887eb2cc7e1f Mon Sep 17 00:00:00 2001 From: Petros Kolyvas Date: Fri, 27 Mar 2020 16:43:49 -0400 Subject: [PATCH 03/23] Added etcdv3 maintainer --- CODEOWNERS | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CODEOWNERS b/CODEOWNERS index 16a1271b3a..d3fd73548a 100644 --- a/CODEOWNERS +++ b/CODEOWNERS @@ -7,7 +7,7 @@ /backend/remote-state/consul @hashicorp/consul /backend/remote-state/cos @likexian /backend/remote-state/etcdv2 Unmaintained -/backend/remote-state/etcdv2 Unmaintained +/backend/remote-state/etcdv2 @bmcstdio /backend/remote-state/gcs @hashicorp/terraform-google /backend/remote-state/http Unmaintained /backend/remote-state/manta Unmaintained From 96e1a1f800a6a886c2ccdd7c8a9de1ae59b2ad8e Mon Sep 17 00:00:00 2001 From: Petros Kolyvas Date: Fri, 27 Mar 2020 17:12:35 -0400 Subject: [PATCH 04/23] more prescriptive Contributor's guide --- .github/CONTRIBUTING.md | 38 ++++++++++++++++++++++++++------------ 1 file changed, 26 insertions(+), 12 deletions(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 52f8555ecd..611ad53797 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -1,32 +1,45 @@ # Contributing to Terraform ------- - This repository contains only Terraform core, which includes the command line interface and the main graph engine. Providers are implemented as plugins that each have their own repository in [the `terraform-providers` organization](https://github.com/terraform-providers) on GitHub. Instructions for developing each provider are in the associated README file. For more information, see [the provider development overview](https://www.terraform.io/docs/plugins/provider.html). ---- -**First:** if you're unsure or afraid of *anything*, just ask or submit the issue anyway. You won't be yelled at for giving your best effort. The worst that can happen is that you'll be politely asked to change something or move . We appreciate any sort of contributions, and don't want a wall of rules to get in the way of that. + -However, for those individuals who want a bit more guidance on the best way to contribute to this project, read on. This document will cover what we're looking for in order to help set some expectations and help you get the most out of participation in this project. +- [Proposing a Change](#proposing-a-change) + - [Caveats & Areas of special concern](#caveats--areas-of-special-concern) + - [State Storage Backends](#state-storage-backends) + - [Provisioners](#provisioners) + - [Pull Request Lifecycle](#pull-request-lifecycle) + - [Getting Your Pull Requests Merged Faster](#getting-your-pull-requests-merged-faster) + - [PR Checks](#pr-checks) +- [Terraform CLI/Core Development Environment](#terraform-clicore-development-environment) +- [Acceptance Tests: Testing interactions with external services](#acceptance-tests-testing-interactions-with-external-services) +- [Generated Code](#generated-code) +- [External Dependencies](#external-dependencies) -Terraform is managed by small core development team and so we aren't always able to respond to every issue or pull request in a timely manner. + + + +This document provides guidance on Terraform contibution recommended practices. It covers what we're looking for in order to help set some expectations and help you get the most out of participation in this project. To record a bug report, enhancement proposal, or give any other product feedback, please [open a GitHub issue](https://github.com/hashicorp/terraform/issues/new/choose) using the most appropriate issue template. Please do fill in all of the information the issue templates request, because we've seen from experience that this will maximize the chance that we'll be able to act on your feedback. ## Proposing a Change -In order to be respectful of the time of community contributors, we prefer to discuss potential changes in GitHub issues prior to implementation. That will allow us to give design feedback up front and set expectations about the scope of the change, and, for larger changes, how best to approach the work such that the Terraform team can review it and merge it along with other concurrent work. +In order to be respectful of the time of community contributors, we aim to discuss potential changes in GitHub issues prior to implementation. That will allow us to give design feedback up front and set expectations about the scope of the change, and, for larger changes, how best to approach the work such that the Terraform team can review it and merge it along with other concurrent work. -If the bug you wish to fix or enhancement you wish to implement isn't already covered by a GitHub issue that contains feedback from the Terraform team, please do start a discussion (either in [a new GitHub issue](https://github.com/hashicorp/terraform/issues/new/choose) or an existing one, as appropriate) before you invest significant development time. If you mention your intent to implement the change described in your issue, the Terraform team can prioritize including implementation-related feedback in the subsequent discussion. +If the bug you wish to fix or enhancement you wish to implement isn't already covered by a GitHub issue that contains feedback from the Terraform team, please do start a discussion (either in [a new GitHub issue](https://github.com/hashicorp/terraform/issues/new/choose) or an existing one, as appropriate) before you invest significant development time. If you mention your intent to implement the change described in your issue, the Terraform team can, as best as possible, prioritize including implementation-related feedback in the subsequent discussion. -At this time, we do not have a formal process for reviewing outside proposals that significantly change Terraform's workflow, its primary usage patterns, and its language. While we do hope to put such a thing in place in the future, we wish to be up front with potential contributors that unfortunately we are unlikely to be able to give prompt feedback for large proposals that could entail a significant design phase, though we are still interested to hear about your use-cases so that we can consider ways to meet them as part of other larger projects. +At this time, we do not have a formal process for reviewing outside proposals that significantly change Terraform's workflow, its primary usage patterns, and its language. Additionally, some seemingly simple proposals can have deep effects across Terraform, which is why we strongly suggest starting with an issue-based proposal. + +For large proposals that could entail a significant design phase, we wish to be up front with potential contributors that, unfortunately, we are unlikely to be able to give prompt feedback. We are still interested to hear about your use-cases so that we can consider ways to meet them as part of other larger projects. Most changes will involve updates to the test suite, and changes to Terraform's documentation. The Terraform team can advise on different testing strategies for specific scenarios, and may ask you to revise the specific phrasing of your proposed documentation prose to match better with the standard "voice" of Terraform's documentation. This repository is primarily maintained by a small team at HashiCorp along with their other responsibilities, so unfortunately we cannot always respond promptly to pull requests, particularly if they do not relate to an existing GitHub issue where the Terraform team has already participated. We *are* grateful for all contributions however, and will give feedback on pull requests as soon as we're able. -### Caveats +### Caveats & Areas of special concern #### State Storage Backends @@ -38,6 +51,10 @@ The Terraform team will not be merging new state storage backends at this time. We are working to remove ourselves from the critical path of state storage backends. Unfortuanately in the mean time, we won't be accepting new backends. +#### Provisioners + +TO ADD + ### Pull Request Lifecycle 1. You are welcome to submit your pull request for commentary or review before it is fully completed. Please prefix the title of your pull request with "[WIP]" to indicate this. It's also a good idea to include specific questions or items you'd like feedback on. @@ -180,6 +197,3 @@ git commit -m "vendor: go get github.com/hashicorp/hcl/v2@2.0.0" ``` You can then make use of the new or updated dependency in new code added in subsequent commits. - -#### - From 61fe0a3402763eae5c66e4803f1a0c1ffb11ffbb Mon Sep 17 00:00:00 2001 From: Petros Kolyvas Date: Fri, 27 Mar 2020 17:20:53 -0400 Subject: [PATCH 05/23] Fixed an ordering/clarity issue with the TOC --- .github/CONTRIBUTING.md | 24 +++++++++++++----------- 1 file changed, 13 insertions(+), 11 deletions(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 611ad53797..b153b4b751 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -4,15 +4,22 @@ This repository contains only Terraform core, which includes the command line in ---- + +This document provides guidance on Terraform contibution recommended practices. It covers what we're looking for in order to help set some expectations and help you get the most out of participation in this project. + +To record a bug report, enhancement proposal, or give any other product feedback, please [open a GitHub issue](https://github.com/hashicorp/terraform/issues/new/choose) using the most appropriate issue template. Please do fill in all of the information the issue templates request, because we've seen from experience that this will maximize the chance that we'll be able to act on your feedback. + +---- + - [Proposing a Change](#proposing-a-change) - - [Caveats & Areas of special concern](#caveats--areas-of-special-concern) - - [State Storage Backends](#state-storage-backends) - - [Provisioners](#provisioners) - - [Pull Request Lifecycle](#pull-request-lifecycle) - - [Getting Your Pull Requests Merged Faster](#getting-your-pull-requests-merged-faster) - - [PR Checks](#pr-checks) + - [Caveats & Areas of special concern](#caveats--areas-of-special-concern) + - [State Storage Backends](#state-storage-backends) + - [Provisioners](#provisioners) + - [Pull Request Lifecycle](#pull-request-lifecycle) + - [Getting Your Pull Requests Merged Faster](#getting-your-pull-requests-merged-faster) + - [PR Checks](#pr-checks) - [Terraform CLI/Core Development Environment](#terraform-clicore-development-environment) - [Acceptance Tests: Testing interactions with external services](#acceptance-tests-testing-interactions-with-external-services) - [Generated Code](#generated-code) @@ -20,11 +27,6 @@ This repository contains only Terraform core, which includes the command line in - -This document provides guidance on Terraform contibution recommended practices. It covers what we're looking for in order to help set some expectations and help you get the most out of participation in this project. - -To record a bug report, enhancement proposal, or give any other product feedback, please [open a GitHub issue](https://github.com/hashicorp/terraform/issues/new/choose) using the most appropriate issue template. Please do fill in all of the information the issue templates request, because we've seen from experience that this will maximize the chance that we'll be able to act on your feedback. - ## Proposing a Change In order to be respectful of the time of community contributors, we aim to discuss potential changes in GitHub issues prior to implementation. That will allow us to give design feedback up front and set expectations about the scope of the change, and, for larger changes, how best to approach the work such that the Terraform team can review it and merge it along with other concurrent work. From 700182dc7aef71d0ab954933dcb9e677834ebb77 Mon Sep 17 00:00:00 2001 From: Petros Kolyvas Date: Tue, 31 Mar 2020 16:13:50 -0400 Subject: [PATCH 06/23] Fixed etcdv3 maintainer and added provisioners --- CODEOWNERS | 37 +++++++++++++++++++++++-------------- 1 file changed, 23 insertions(+), 14 deletions(-) diff --git a/CODEOWNERS b/CODEOWNERS index d3fd73548a..6d7e310b69 100644 --- a/CODEOWNERS +++ b/CODEOWNERS @@ -1,17 +1,26 @@ # Each line is a file pattern followed by one or more owners. # More on CODEOWNERS files: https://help.github.com/en/github/creating-cloning-and-archiving-repositories/about-code-owners -# Remote-state backend -/backend/remote-state/artifactory Unmaintained -/backend/remote-state/azure @hashicorp/terraform-azure -/backend/remote-state/consul @hashicorp/consul -/backend/remote-state/cos @likexian -/backend/remote-state/etcdv2 Unmaintained -/backend/remote-state/etcdv2 @bmcstdio -/backend/remote-state/gcs @hashicorp/terraform-google -/backend/remote-state/http Unmaintained -/backend/remote-state/manta Unmaintained -/backend/remote-state/oss @xiaozhu36 -/backend/remote-state/pg Unmaintained -/backend/remote-state/s3 @hashicorp/terraform-aws -/backend/remote-state/swift Unmaintained \ No newline at end of file +# Remote-state backend # Maintainer +/backend/remote-state/artifactory Unmaintained +/backend/remote-state/azure @hashicorp/terraform-azure +/backend/remote-state/consul @hashicorp/consul +/backend/remote-state/cos @likexian +/backend/remote-state/etcdv2 Unmaintained +/backend/remote-state/etcdv3 @bmcstdio +/backend/remote-state/gcs @hashicorp/terraform-google +/backend/remote-state/http Unmaintained +/backend/remote-state/manta Unmaintained +/backend/remote-state/oss @xiaozhu36 +/backend/remote-state/pg Unmaintained +/backend/remote-state/s3 @hashicorp/terraform-aws +/backend/remote-state/swift Unmaintained + +# Provisioners +builtin/provisioners/chef Unmaintained +builtin/provisioners/file @hashicorp/terraform-core +builtin/provisioners/habitat Unmaintained +builtin/provisioners/local-exec @hashicorp/terraform-core +builtin/provisioners/puppet Unmaintained +builtin/provisioners/remote-exec @hashicorp/terraform-core +builtin/provisioners/salt-masterless Unmaintained \ No newline at end of file From 3725b4b3a02535e8d636a55f593605e6b0a0c3f0 Mon Sep 17 00:00:00 2001 From: Petros Kolyvas Date: Wed, 1 Apr 2020 15:09:15 -0400 Subject: [PATCH 07/23] Updated provisioners & added team-tf-core to http backend ownship, possibly in error. --- CODEOWNERS | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CODEOWNERS b/CODEOWNERS index 6d7e310b69..e7300a59d2 100644 --- a/CODEOWNERS +++ b/CODEOWNERS @@ -9,7 +9,7 @@ /backend/remote-state/etcdv2 Unmaintained /backend/remote-state/etcdv3 @bmcstdio /backend/remote-state/gcs @hashicorp/terraform-google -/backend/remote-state/http Unmaintained +/backend/remote-state/http @hashicorp/terraform-core /backend/remote-state/manta Unmaintained /backend/remote-state/oss @xiaozhu36 /backend/remote-state/pg Unmaintained From 9d097195a306dcb5da468d8832e2d6d4bc7b4c68 Mon Sep 17 00:00:00 2001 From: Petros Kolyvas Date: Wed, 1 Apr 2020 15:28:50 -0400 Subject: [PATCH 08/23] Fixing some minor formatting issues They don't seem to be present on `localhost` --- CODEOWNERS | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/CODEOWNERS b/CODEOWNERS index e7300a59d2..faffd59772 100644 --- a/CODEOWNERS +++ b/CODEOWNERS @@ -18,9 +18,9 @@ # Provisioners builtin/provisioners/chef Unmaintained -builtin/provisioners/file @hashicorp/terraform-core -builtin/provisioners/habitat Unmaintained +builtin/provisioners/file @hashicorp/terraform-core +builtin/provisioners/habitat Unmaintained builtin/provisioners/local-exec @hashicorp/terraform-core builtin/provisioners/puppet Unmaintained -builtin/provisioners/remote-exec @hashicorp/terraform-core -builtin/provisioners/salt-masterless Unmaintained \ No newline at end of file +builtin/provisioners/remote-exec @hashicorp/terraform-core +builtin/provisioners/salt-masterless Unmaintained From ed9a2ea11887083a369ceb318f3c68b9f139ba2f Mon Sep 17 00:00:00 2001 From: Petros Kolyvas Date: Wed, 1 Apr 2020 15:30:17 -0400 Subject: [PATCH 09/23] OCD spacing, formatting of Codeowners --- CODEOWNERS | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/CODEOWNERS b/CODEOWNERS index e7300a59d2..ec1bb4d0a8 100644 --- a/CODEOWNERS +++ b/CODEOWNERS @@ -17,10 +17,10 @@ /backend/remote-state/swift Unmaintained # Provisioners -builtin/provisioners/chef Unmaintained -builtin/provisioners/file @hashicorp/terraform-core -builtin/provisioners/habitat Unmaintained -builtin/provisioners/local-exec @hashicorp/terraform-core -builtin/provisioners/puppet Unmaintained -builtin/provisioners/remote-exec @hashicorp/terraform-core -builtin/provisioners/salt-masterless Unmaintained \ No newline at end of file +builtin/provisioners/chef Unmaintained +builtin/provisioners/file @hashicorp/terraform-core +builtin/provisioners/habitat Unmaintained +builtin/provisioners/local-exec @hashicorp/terraform-core +builtin/provisioners/puppet Unmaintained +builtin/provisioners/remote-exec @hashicorp/terraform-core +builtin/provisioners/salt-masterless Unmaintained \ No newline at end of file From a3dcda6ae51baf396c945638e0b25270271003bd Mon Sep 17 00:00:00 2001 From: Petros Kolyvas Date: Wed, 1 Apr 2020 15:32:47 -0400 Subject: [PATCH 10/23] tabs are hard --- CODEOWNERS | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/CODEOWNERS b/CODEOWNERS index bcc4c2dda2..8417e9815e 100644 --- a/CODEOWNERS +++ b/CODEOWNERS @@ -17,11 +17,11 @@ /backend/remote-state/swift Unmaintained # Provisioners -builtin/provisioners/chef Unmaintained -builtin/provisioners/file @hashicorp/terraform-core -builtin/provisioners/habitat Unmaintained -builtin/provisioners/local-exec @hashicorp/terraform-core -builtin/provisioners/puppet Unmaintained -builtin/provisioners/remote-exec @hashicorp/terraform-core -builtin/provisioners/salt-masterless Unmaintained +builtin/provisioners/chef Unmaintained +builtin/provisioners/file @hashicorp/terraform-core +builtin/provisioners/habitat Unmaintained +builtin/provisioners/local-exec @hashicorp/terraform-core +builtin/provisioners/puppet Unmaintained +builtin/provisioners/remote-exec @hashicorp/terraform-core +builtin/provisioners/salt-masterless Unmaintained From 942b4df545a84b800dff60271cee760342e95d49 Mon Sep 17 00:00:00 2001 From: Petros Kolyvas Date: Fri, 3 Apr 2020 16:00:19 -0400 Subject: [PATCH 11/23] Added a provisioners section and a maintainers section --- .github/CONTRIBUTING.md | 44 ++++++++++++++++++++++++++++++++++------- 1 file changed, 37 insertions(+), 7 deletions(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index b153b4b751..4947ea0857 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -27,6 +27,16 @@ To record a bug report, enhancement proposal, or give any other product feedback +##Contributing Fixes + +It can be tempting to want to dive into an open source project and help _build the thing_ you believe you're missing. It's a wonderful and helpful intention. However, Terraform is a complex tool. Many seemingly simple changes can have serious effects on other areas of the code and it can take some time to become familiar with the effects of even basic changes. The Terraform team is not immune to unintended and sometimes undesirable changes. We do take our work seriously, and appreciate the globally diverse community that relies on Terraform for workflows of all sizes and criticality. + +As a result of Terraform's complexity and high bar for stability, the most straightforward way to start helping with the Terraform project is to pick an existing bug and [get to work](#terraform-clicore-development-environment). + +For new contributors we've labeled a few issues with `Good First Issue` as a nod to issues which will help get you familiar with Terraform development, while also providing an onramp to the codebase itself. + +Read the documentation, and don't be afraid to ask questions. + ## Proposing a Change In order to be respectful of the time of community contributors, we aim to discuss potential changes in GitHub issues prior to implementation. That will allow us to give design feedback up front and set expectations about the scope of the change, and, for larger changes, how best to approach the work such that the Terraform team can review it and merge it along with other concurrent work. @@ -41,21 +51,39 @@ Most changes will involve updates to the test suite, and changes to Terraform's This repository is primarily maintained by a small team at HashiCorp along with their other responsibilities, so unfortunately we cannot always respond promptly to pull requests, particularly if they do not relate to an existing GitHub issue where the Terraform team has already participated. We *are* grateful for all contributions however, and will give feedback on pull requests as soon as we're able. -### Caveats & Areas of special concern +### Caveats & areas of special concern + +There are some areas of Terrafor which are of special concern to the Terraform team. #### State Storage Backends -The Terraform team is not merging PRs for new state storage backends. Our current priority regarding state storage backends is to find maintainers for existing backends and work towards removal of those without maintainership. +The Terraform team is not merging PRs for new state storage backends at the current time. Our priority regarding state storage backends is to find maintainers for existing backends and work towards removal of those without maintainership. -Please see the CODEOWNERS file for the status of a given backend. +Please see the [CODEOWNERS](https://github.com/hashicorp/terraform/blob/master/CODEOWNERS) file for the status of a given backend. Community members with an interest in a particular standard backend are welcome to help maintain it. -The Terraform team will not be merging new state storage backends at this time. The burden it places on a team to setup an environment and cloud service provider account, or a new database/storage/key-value service, in order to build and test remote state storage prevents us from moving Terraform forward in other ways. +At the current time, merging state storage backends places a significant burden on the Terraform team to setup an environment and cloud service provider account, or a new database/storage/key-value service, in order to build and test remote state storage backends. The time and complexity of doing so prevents us from moving Terraform forward in other ways. -We are working to remove ourselves from the critical path of state storage backends. Unfortuanately in the mean time, we won't be accepting new backends. +We are working to remove ourselves from the critical path of state storage backends by moving them towarsds a plugin model like providers. In the mean time, we won't be accepting new remote state backends into Terraform. #### Provisioners -TO ADD +Provisioners are an area of concern in Terraform for a number of reasons. Chiefly, they are often used in the place of configuration management tools or custom providers. + +From our [documentation](https://www.terraform.io/docs/provisioners/index.html): + +> ... they [...] add a considerable amount of complexity and uncertainty to Terraform usage.[...] we still recommend attempting to solve it [your problem] using other techniques first, and use provisioners only if there is no other option. + +The Terraform team is in the process of building a way forward whilch continues to decrease reliance on provisioners. In the mean time however, as our documentation indicates, they are a tool of last resort. As such expect that PRs and issues for provisioners are not high in priority. + +Please see the [CODEOWNERS](https://github.com/hashicorp/terraform/blob/master/CODEOWNERS) file for the status of a given provisioners. Community members with an interest in a particular provisioner are welcome to help maintain it. + +####Maintainers + +Maintainers are key contributors to our Open Source project. They contribute their time and expertise and we ask that the community take extra special care to be mindful of this when interacting with them. + +For code that has a listed maintainer or maintainers, the Terraform team will highlight them for participation in PRs. However, please consider the change proposal process when doing so. + +There is no expectation on response time for our maintainers; they may be indisposed for prolonged periods of time. Please be patient. Discussions on when code becomes "unmaintained" will be on a case-by-case basis. ### Pull Request Lifecycle @@ -88,6 +116,8 @@ The following checks run when a PR is opened: -> **Note:** We are still deciding on the right targets for our code coverage check. A failure in `codecov` does not necessarily mean that your PR will not be approved or merged. +---- + ## Terraform CLI/Core Development Environment This repository contains the source code for Terraform CLI, which is the main component of Terraform that contains the core Terraform engine. @@ -198,4 +228,4 @@ git add go.mod go.sum vendor git commit -m "vendor: go get github.com/hashicorp/hcl/v2@2.0.0" ``` -You can then make use of the new or updated dependency in new code added in subsequent commits. +You can then make use of the new or updated dependency in new code added in subsequent commits. \ No newline at end of file From ca90de14ec768802f501eafd84bfe8e0435449e4 Mon Sep 17 00:00:00 2001 From: Petros Kolyvas Date: Fri, 3 Apr 2020 16:04:55 -0400 Subject: [PATCH 12/23] Updated Contribution Guide TOC --- .github/CONTRIBUTING.md | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 4947ea0857..556ad5ec1a 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -13,13 +13,15 @@ To record a bug report, enhancement proposal, or give any other product feedback +- [Contributing Fixes](#contributing-fixes) - [Proposing a Change](#proposing-a-change) - - [Caveats & Areas of special concern](#caveats--areas-of-special-concern) - - [State Storage Backends](#state-storage-backends) - - [Provisioners](#provisioners) - - [Pull Request Lifecycle](#pull-request-lifecycle) - - [Getting Your Pull Requests Merged Faster](#getting-your-pull-requests-merged-faster) - - [PR Checks](#pr-checks) + - [Caveats & areas of special concern](#caveats--areas-of-special-concern) + - [State Storage Backends](#state-storage-backends) + - [Provisioners](#provisioners) + - [Maintainers](#maintainers) + - [Pull Request Lifecycle](#pull-request-lifecycle) + - [Getting Your Pull Requests Merged Faster](#getting-your-pull-requests-merged-faster) + - [PR Checks](#pr-checks) - [Terraform CLI/Core Development Environment](#terraform-clicore-development-environment) - [Acceptance Tests: Testing interactions with external services](#acceptance-tests-testing-interactions-with-external-services) - [Generated Code](#generated-code) @@ -85,6 +87,8 @@ For code that has a listed maintainer or maintainers, the Terraform team will hi There is no expectation on response time for our maintainers; they may be indisposed for prolonged periods of time. Please be patient. Discussions on when code becomes "unmaintained" will be on a case-by-case basis. +If an an unmaintained area of code interests you and you'd like to become a maintainer, you may simply make a PR against our [CODEWONERS](https://github.com/hashicorp/terraform/blob/master/CODEOWNERS) file with your github handle attached to the approriate area. If there is a maintainer or team of maintainers for that area, please coordinate with them as necessary. + ### Pull Request Lifecycle 1. You are welcome to submit your pull request for commentary or review before it is fully completed. Please prefix the title of your pull request with "[WIP]" to indicate this. It's also a good idea to include specific questions or items you'd like feedback on. From db5878ff044e1254ca4d3060c890b3841031fedc Mon Sep 17 00:00:00 2001 From: Petros Kolyvas Date: Fri, 3 Apr 2020 16:11:42 -0400 Subject: [PATCH 13/23] More updates and fixes, some grammatical, some clarity issues, one markdown bugaboo --- .github/CONTRIBUTING.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 556ad5ec1a..cb8dfa6f32 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -55,7 +55,7 @@ This repository is primarily maintained by a small team at HashiCorp along with ### Caveats & areas of special concern -There are some areas of Terrafor which are of special concern to the Terraform team. +There are some areas of Terraform which are of special concern to the Terraform team. #### State Storage Backends @@ -63,9 +63,9 @@ The Terraform team is not merging PRs for new state storage backends at the curr Please see the [CODEOWNERS](https://github.com/hashicorp/terraform/blob/master/CODEOWNERS) file for the status of a given backend. Community members with an interest in a particular standard backend are welcome to help maintain it. -At the current time, merging state storage backends places a significant burden on the Terraform team to setup an environment and cloud service provider account, or a new database/storage/key-value service, in order to build and test remote state storage backends. The time and complexity of doing so prevents us from moving Terraform forward in other ways. +Currently, merging state storage backends places a significant burden on the Terraform team. The team must setup an environment and cloud service provider account, or a new database/storage/key-value service, in order to build and test remote state storage backends. The time and complexity of doing so prevents us from moving Terraform forward in other ways. -We are working to remove ourselves from the critical path of state storage backends by moving them towarsds a plugin model like providers. In the mean time, we won't be accepting new remote state backends into Terraform. +We are working to remove ourselves from the critical path of state storage backends by moving them towards a plugin model. In the mean time, we won't be accepting new remote state backends into Terraform. #### Provisioners @@ -83,7 +83,7 @@ Please see the [CODEOWNERS](https://github.com/hashicorp/terraform/blob/master/C Maintainers are key contributors to our Open Source project. They contribute their time and expertise and we ask that the community take extra special care to be mindful of this when interacting with them. -For code that has a listed maintainer or maintainers, the Terraform team will highlight them for participation in PRs. However, please consider the change proposal process when doing so. +For code that has a listed maintainer or maintainers in our [CODEWONERS](https://github.com/hashicorp/terraform/blob/master/CODEOWNERS) file, the Terraform team will highlight them for participation in PRs which relate to the area of code they maintain. The expectation is that a maintainer will review the code and work with the PR contributor before the code is merged by the Terraform team. There is no expectation on response time for our maintainers; they may be indisposed for prolonged periods of time. Please be patient. Discussions on when code becomes "unmaintained" will be on a case-by-case basis. From cd54300621501287a448b6a143a090dafe426053 Mon Sep 17 00:00:00 2001 From: Petros Kolyvas Date: Fri, 3 Apr 2020 16:13:36 -0400 Subject: [PATCH 14/23] Why won't you h4 maintainers. --- .github/CONTRIBUTING.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index cb8dfa6f32..a822703e90 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -79,6 +79,8 @@ The Terraform team is in the process of building a way forward whilch continues Please see the [CODEOWNERS](https://github.com/hashicorp/terraform/blob/master/CODEOWNERS) file for the status of a given provisioners. Community members with an interest in a particular provisioner are welcome to help maintain it. + + ####Maintainers Maintainers are key contributors to our Open Source project. They contribute their time and expertise and we ask that the community take extra special care to be mindful of this when interacting with them. From c7cae980764737aa50c663fe01e2bcf483a6040d Mon Sep 17 00:00:00 2001 From: Petros Kolyvas Date: Fri, 3 Apr 2020 16:14:08 -0400 Subject: [PATCH 15/23] GitHub hates me --- .github/CONTRIBUTING.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index a822703e90..3ca1618338 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -79,9 +79,7 @@ The Terraform team is in the process of building a way forward whilch continues Please see the [CODEOWNERS](https://github.com/hashicorp/terraform/blob/master/CODEOWNERS) file for the status of a given provisioners. Community members with an interest in a particular provisioner are welcome to help maintain it. - - -####Maintainers +#### Maintainers Maintainers are key contributors to our Open Source project. They contribute their time and expertise and we ask that the community take extra special care to be mindful of this when interacting with them. @@ -234,4 +232,4 @@ git add go.mod go.sum vendor git commit -m "vendor: go get github.com/hashicorp/hcl/v2@2.0.0" ``` -You can then make use of the new or updated dependency in new code added in subsequent commits. \ No newline at end of file +You can then make use of the new or updated dependency in new code added in subsequent commits. From ad15e4a116eb7a9922db998d50017ee2026af0b9 Mon Sep 17 00:00:00 2001 From: Petros Kolyvas Date: Fri, 3 Apr 2020 16:15:09 -0400 Subject: [PATCH 16/23] A few more spacing issues in MD format for GH --- .github/CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 3ca1618338..4d366e4ed2 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -29,7 +29,7 @@ To record a bug report, enhancement proposal, or give any other product feedback -##Contributing Fixes +## Contributing Fixes It can be tempting to want to dive into an open source project and help _build the thing_ you believe you're missing. It's a wonderful and helpful intention. However, Terraform is a complex tool. Many seemingly simple changes can have serious effects on other areas of the code and it can take some time to become familiar with the effects of even basic changes. The Terraform team is not immune to unintended and sometimes undesirable changes. We do take our work seriously, and appreciate the globally diverse community that relies on Terraform for workflows of all sizes and criticality. From 10437b4b15e7974b3895bd4db4cbd2455bfbd96e Mon Sep 17 00:00:00 2001 From: Petros Kolyvas Date: Mon, 6 Apr 2020 12:09:22 -0400 Subject: [PATCH 17/23] Update .github/CONTRIBUTING.md Co-Authored-By: Alisdair McDiarmid --- .github/CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 4d366e4ed2..c624cc0603 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -130,7 +130,7 @@ The HashiCorp-maintained Terraform providers are also open source but are not in This repository also does not include the source code for some other parts of the Terraform product including Terraform Cloud, Terraform Enterprise, and the Terraform Registry. Those components are not open source, though if you have feedback about them (including bug reports) please do feel free to [open a GitHub issue on this repository](https://github.com/hashicorp/terraform/issues/new/choose). ------- +--- If you wish to work on the Terraform CLI source code, you'll first need to install the [Go](https://golang.org/) compiler and the version control system [Git](https://git-scm.com/). From 6ff988a423859bec5fe23d05579d6d35e2054d1e Mon Sep 17 00:00:00 2001 From: Petros Kolyvas Date: Mon, 6 Apr 2020 12:10:27 -0400 Subject: [PATCH 18/23] Apply suggestions from code review Alisdair's fixes. Co-Authored-By: Alisdair McDiarmid --- .github/CONTRIBUTING.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index c624cc0603..560ceee37f 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -1,15 +1,15 @@ -# Contributing to Terraform +# Contributing to Terraform This repository contains only Terraform core, which includes the command line interface and the main graph engine. Providers are implemented as plugins that each have their own repository in [the `terraform-providers` organization](https://github.com/terraform-providers) on GitHub. Instructions for developing each provider are in the associated README file. For more information, see [the provider development overview](https://www.terraform.io/docs/plugins/provider.html). ----- +--- -This document provides guidance on Terraform contibution recommended practices. It covers what we're looking for in order to help set some expectations and help you get the most out of participation in this project. +This document provides guidance on Terraform contribution recommended practices. It covers what we're looking for in order to help set some expectations and help you get the most out of participation in this project. To record a bug report, enhancement proposal, or give any other product feedback, please [open a GitHub issue](https://github.com/hashicorp/terraform/issues/new/choose) using the most appropriate issue template. Please do fill in all of the information the issue templates request, because we've seen from experience that this will maximize the chance that we'll be able to act on your feedback. ----- +--- From 77ebf266f3dac07c4ceb81aa385656f65976a0ba Mon Sep 17 00:00:00 2001 From: Petros Kolyvas Date: Mon, 6 Apr 2020 12:13:46 -0400 Subject: [PATCH 19/23] Restored the note about our community guidelines --- .github/CONTRIBUTING.md | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 4d366e4ed2..ba42ae3b74 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -4,6 +4,7 @@ This repository contains only Terraform core, which includes the command line in ---- +**All communication on GitHub, the community forum, and other HashiCorp-provided communication channels is subject to [the HashiCorp community guidelines](https://www.hashicorp.com/community-guidelines).** This document provides guidance on Terraform contibution recommended practices. It covers what we're looking for in order to help set some expectations and help you get the most out of participation in this project. From 6529a7c6e9114351752c300c8304fee85a7ae397 Mon Sep 17 00:00:00 2001 From: Petros Kolyvas Date: Mon, 6 Apr 2020 12:59:38 -0400 Subject: [PATCH 20/23] Kristin's comments & suggested changes --- .github/CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index a93e645712..964996b0a3 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -60,7 +60,7 @@ There are some areas of Terraform which are of special concern to the Terraform #### State Storage Backends -The Terraform team is not merging PRs for new state storage backends at the current time. Our priority regarding state storage backends is to find maintainers for existing backends and work towards removal of those without maintainership. +The Terraform team is not merging PRs for new state storage backends at the current time. Our priority regarding state storage backends is to find maintainers for existing backends and remove those backends without maintainers. Please see the [CODEOWNERS](https://github.com/hashicorp/terraform/blob/master/CODEOWNERS) file for the status of a given backend. Community members with an interest in a particular standard backend are welcome to help maintain it. From 783c06b6da2fb2e451fe5bd33e961e5d3985b34d Mon Sep 17 00:00:00 2001 From: Petros Kolyvas Date: Mon, 6 Apr 2020 13:25:17 -0400 Subject: [PATCH 21/23] Kristin's corrections Co-Authored-By: Kristin Laemmert --- .github/CONTRIBUTING.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index a93e645712..59e56875cd 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -76,9 +76,9 @@ From our [documentation](https://www.terraform.io/docs/provisioners/index.html): > ... they [...] add a considerable amount of complexity and uncertainty to Terraform usage.[...] we still recommend attempting to solve it [your problem] using other techniques first, and use provisioners only if there is no other option. -The Terraform team is in the process of building a way forward whilch continues to decrease reliance on provisioners. In the mean time however, as our documentation indicates, they are a tool of last resort. As such expect that PRs and issues for provisioners are not high in priority. +The Terraform team is in the process of building a way forward which continues to decrease reliance on provisioners. In the mean time however, as our documentation indicates, they are a tool of last resort. As such expect that PRs and issues for provisioners are not high in priority. -Please see the [CODEOWNERS](https://github.com/hashicorp/terraform/blob/master/CODEOWNERS) file for the status of a given provisioners. Community members with an interest in a particular provisioner are welcome to help maintain it. +Please see the [CODEOWNERS](https://github.com/hashicorp/terraform/blob/master/CODEOWNERS) file for the status of a given provisioner. Community members with an interest in a particular provisioner are welcome to help maintain it. #### Maintainers @@ -105,7 +105,7 @@ It is much easier to review pull requests that are: 1. Well-documented: Try to explain in the pull request comments what your change does, why you have made the change, and provide instructions for how to produce the new behavior introduced in the pull request. If you can, provide screen captures or terminal output to show what the changes look like. This helps the reviewers understand and test the change. 2. Small: Try to only make one change per pull request. If you found two bugs and want to fix them both, that's *awesome*, but it's still best to submit the fixes as separate pull requests. This makes it much easier for reviewers to keep in their heads all of the implications of individual code changes, and that means the PR takes less effort and energy to merge. In general, the smaller the pull request, the sooner reviewers will be able to make time to review it. -3. Passing Tests: Based on how much time we have, we may not review pull requests which aren't passing our tests. (Look below for advice on how to run unit tests). If you need help figuring out why tests are failing, please feel free to ask, but while we're happy to give guidance it is generally your responsibility to make sure that tests are passing. If your pull request changes an interface or invalidates an assumption that causes a bunch of tests to fail, then you need to fix those tests before we can merge your PR. +3. Passing Tests: Based on how much time we have, we may not review pull requests which aren't passing our tests (look below for advice on how to run unit tests). If you need help figuring out why tests are failing, please feel free to ask, but while we're happy to give guidance it is generally your responsibility to make sure that tests are passing. If your pull request changes an interface or invalidates an assumption that causes a bunch of tests to fail, then you need to fix those tests before we can merge your PR. If we request changes, try to make those changes in a timely manner. Otherwise, PRs can go stale and be a lot more work for all of us to merge in the future. From e92b8a82f407c99edd200ccff67884697f4b1753 Mon Sep 17 00:00:00 2001 From: Petros Kolyvas Date: Mon, 6 Apr 2020 16:43:11 -0400 Subject: [PATCH 22/23] Pam & Kristin's feedback & some more suggested changed. --- .github/CONTRIBUTING.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 964996b0a3..a571f8cc6c 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -38,7 +38,7 @@ As a result of Terraform's complexity and high bar for stability, the most strai For new contributors we've labeled a few issues with `Good First Issue` as a nod to issues which will help get you familiar with Terraform development, while also providing an onramp to the codebase itself. -Read the documentation, and don't be afraid to ask questions. +Read the documentation, and don't be afraid to [ask questions](https://discuss.hashicorp.com/c/terraform-core/27). ## Proposing a Change @@ -52,7 +52,7 @@ For large proposals that could entail a significant design phase, we wish to be Most changes will involve updates to the test suite, and changes to Terraform's documentation. The Terraform team can advise on different testing strategies for specific scenarios, and may ask you to revise the specific phrasing of your proposed documentation prose to match better with the standard "voice" of Terraform's documentation. -This repository is primarily maintained by a small team at HashiCorp along with their other responsibilities, so unfortunately we cannot always respond promptly to pull requests, particularly if they do not relate to an existing GitHub issue where the Terraform team has already participated. We *are* grateful for all contributions however, and will give feedback on pull requests as soon as we're able. +This repository is primarily maintained by a small team at HashiCorp along with their other responsibilities, so unfortunately we cannot always respond promptly to pull requests, particularly if they do not relate to an existing GitHub issue where the Terraform team has already participated and indicated willingness to work on the issue or accept PRs for the proposal. We *are* grateful for all contributions however, and will give feedback on pull requests as soon as we're able. ### Caveats & areas of special concern @@ -92,12 +92,12 @@ If an an unmaintained area of code interests you and you'd like to become a main ### Pull Request Lifecycle -1. You are welcome to submit your pull request for commentary or review before it is fully completed. Please prefix the title of your pull request with "[WIP]" to indicate this. It's also a good idea to include specific questions or items you'd like feedback on. -2. Once you believe your pull request is ready to be merged, you can remove any "[WIP]" prefix from the title and a core team member will review. -3. When time permits Terraform's core team members will look over your contribution and either merge, or provide comments letting you know if there is anything left to do. It may take some time for us to respond. We may also have questions that we need answered about the code, either because something doesn't make sense to us or because we want to understand your thought process. We'd kindly ask that you do not target specific team members. +1. You are welcome to submit a [draft pull request](https://github.blog/2019-02-14-introducing-draft-pull-requests/) for commentary or review before it is fully completed. It's also a good idea to include specific questions or items you'd like feedback on. +2. Once you believe your pull request is ready to be merged you can create your pull request. +3. When time permits Terraform's core team members will look over your contribution and either merge, or provide comments letting you know if there is anything left to do. It may take some time for us to respond. We may also have questions that we need answered about the code, either because something doesn't make sense to us or because we want to understand your thought process. We kindly ask that you do not target specific team members. 4. If we have requested changes, you can either make those changes or, if you disagree with the suggested changes, we can have a conversation about our reasoning and agree on a path forward. This may be a multi-step process. Our view is that pull requests are a chance to collaborate, and we welcome conversations about how to do things better. It is the contributor's responsibility to address any changes requested. While reviewers are happy to give guidance, it is unsustainable for us to perform the coding work necessary to get a PR into a mergeable state. 5. Once all outstanding comments and checklist items have been addressed, your contribution will be merged! Merged PRs may or may not be included in the next release based on changes the Terraform teams deems as breaking or not. The core team takes care of updating the [CHANGELOG.md](https://github.com/hashicorp/terraform/blob/master/CHANGELOG.md) as they merge. -6. In some cases, we might decide that a PR should be closed without merging. We'll make sure to provide clear reasoning when this happens. Following the above +6. In some cases, we might decide that a PR should be closed without merging. We'll make sure to provide clear reasoning when this happens. Following the recommended process above is one of the ways to ensure you don't spend time on a PR we can't or won't merge. #### Getting Your Pull Requests Merged Faster From e7609274088d818399179bd5a85d8f2bbb1c67d4 Mon Sep 17 00:00:00 2001 From: Petros Kolyvas Date: Mon, 6 Apr 2020 16:43:46 -0400 Subject: [PATCH 23/23] Update .github/CONTRIBUTING.md Co-Authored-By: Pam Selle --- .github/CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 59e56875cd..86d97a35a3 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -66,7 +66,7 @@ Please see the [CODEOWNERS](https://github.com/hashicorp/terraform/blob/master/C Currently, merging state storage backends places a significant burden on the Terraform team. The team must setup an environment and cloud service provider account, or a new database/storage/key-value service, in order to build and test remote state storage backends. The time and complexity of doing so prevents us from moving Terraform forward in other ways. -We are working to remove ourselves from the critical path of state storage backends by moving them towards a plugin model. In the mean time, we won't be accepting new remote state backends into Terraform. +We are working to remove ourselves from the critical path of state storage backends by moving them towards a plugin model. In the meantime, we won't be accepting new remote state backends into Terraform. #### Provisioners