mirror of
https://github.com/opentofu/opentofu.git
synced 2024-12-28 01:41:48 -06:00
18c88f5a41
For a while now we've been gathering some codebase-level docs that felt out-of-place on the main Terraform website (since they are about the implementation, not usage) but we had no existing suitable place to put them. In order to make this information more available (and, hopefully, more likely to stay up-to-date as we change things), here we'll establish the "docs" directory as a place to keep documentation aimed at those who are working on code changes to the Terraform Core codebase. User-oriented docs should never appear in this directory. The Terraform website is always the better place for those. The set of docs here is rudimentary to start and we'll see if it makes sense to expand and reorganize it over time based on the experience with having these initial docs available.
96 lines
5.0 KiB
Markdown
96 lines
5.0 KiB
Markdown
# Maintainer's Etiquette
|
|
|
|
Are you a core maintainer of Terraform? Great! Here's a few notes
|
|
to help you get comfortable when working on the project.
|
|
|
|
This documentation is somewhat outdated since it still includes provider-related
|
|
information even though providers are now developed in their own separate
|
|
codebases, but the general information is still valid.
|
|
|
|
## Expectations
|
|
|
|
We value the time you spend on the project and as such your maintainer status
|
|
doesn't imply any obligations to do any specific work.
|
|
|
|
### Your PRs
|
|
|
|
These apply to all contributors, but maintainers should lead by examples! :wink:
|
|
|
|
- for `provider/*` PRs it's useful to attach test results & advise on how to run the relevant tests
|
|
- for `bug`fixes it's useful to attach repro case, ideally in a form of a test
|
|
|
|
### PRs/issues from others
|
|
|
|
- you're welcomed to triage (attach labels to) other PRs and issues
|
|
- we generally use 2-label system (= at least 2 labels per issue/PR) where one label is generic and other one API-specific, e.g. `enhancement` & `provider/aws`
|
|
|
|
## Merging
|
|
|
|
- you're free to review PRs from the community or other HC employees and give :+1: / :-1:
|
|
- if the PR submitter has push privileges (recognizable via `Collaborator`, `Member` or `Owner` badge) - we expect **the submitter** to merge their own PR after receiving a positive review from either HC employee or another maintainer. _Exceptions apply - see below._
|
|
- we prefer to use the Github's interface or API to do this, just click the green button
|
|
- squash?
|
|
- squash when you think the commit history is irrelevant (will not be helpful for any readers in T+6months)
|
|
- Add the new PR to the **Changelog** if it may affect the user (almost any PR except test changes and docs updates)
|
|
- we prefer to use the Github's web interface to modify the Changelog and use `[GH-12345]` to format the PR number. These will be turned into links as part of the release process. Breaking changes should be always documented separately.
|
|
|
|
## Release process
|
|
|
|
- HC employees are responsible for cutting new releases
|
|
- The employee cutting the release will always notify all maintainers via Slack channel before & after each release
|
|
so you can avoid merging PRs during the release process.
|
|
|
|
## Exceptions
|
|
|
|
Any PR that is significantly changing or even breaking user experience cross-providers should always get at least one :+1: from a HC employee prior to merge.
|
|
|
|
It is generally advisable to leave PRs labelled as `core` for HC employees to review and merge.
|
|
|
|
Examples include:
|
|
- adding/changing/removing a CLI (sub)command or a [flag](https://github.com/hashicorp/terraform/pull/12939)
|
|
- introduce a new feature like [Environments](https://github.com/hashicorp/terraform/pull/12182) or [Shadow Graph](https://github.com/hashicorp/terraform/pull/9334)
|
|
- changing config (HCL) like [adding support for lists](https://github.com/hashicorp/terraform/pull/6322)
|
|
- change of the [build process or test environment](https://github.com/hashicorp/terraform/pull/9355)
|
|
|
|
## Breaking Changes
|
|
|
|
- we always try to avoid breaking changes where possible and/or defer them to the nearest major release
|
|
- [state migration](https://github.com/hashicorp/terraform/blob/2fe5976aec290f4b53f07534f4cde13f6d877a3f/helper/schema/resource.go#L33-L56) may help you avoid breaking changes, see [example](https://github.com/hashicorp/terraform/blob/351c6bed79abbb40e461d3f7d49fe4cf20bced41/builtin/providers/aws/resource_aws_route53_record_migrate.go)
|
|
- either way BCs should be clearly documented in special section of the Changelog
|
|
- Any BC must always receive at least one :+1: from HC employee prior to merge, two :+1:s are advisable
|
|
|
|
### Examples of Breaking Changes
|
|
|
|
- https://github.com/hashicorp/terraform/pull/12396
|
|
- https://github.com/hashicorp/terraform/pull/13872
|
|
- https://github.com/hashicorp/terraform/pull/13752
|
|
|
|
## Unsure?
|
|
|
|
If you're unsure about anything, ask in the committer's Slack channel.
|
|
|
|
## New Providers
|
|
|
|
These will require :+1: and some extra effort from HC employee.
|
|
|
|
We expect all acceptance tests to be as self-sustainable as possible
|
|
to keep the bar for running any acceptance test low for anyone
|
|
outside of HashiCorp or core maintainers team.
|
|
|
|
We expect any test to run **in parallel** alongside any other test (even the same test).
|
|
To ensure this is possible, we need all tests to avoid sharing namespaces or using static unique names.
|
|
In rare occasions this may require the use of mutexes in the resource code.
|
|
|
|
### New Remote-API-based provider (e.g. AWS, Google Cloud, PagerDuty, Atlas)
|
|
|
|
We will need some details about who to contact or where to register for a new account
|
|
and generally we can't merge providers before ensuring we have a way to test them nightly,
|
|
which usually involves setting up a new account and obtaining API credentials.
|
|
|
|
### Local provider (e.g. MySQL, PostgreSQL, Kubernetes, Vault)
|
|
|
|
We will need either Terraform configs that will set up the underlying test infrastructure
|
|
(e.g. GKE cluster for Kubernetes) or Dockerfile(s) that will prepare test environment (e.g. MySQL)
|
|
and expose the endpoint for testing.
|
|
|