How to contribute

Contributing to Terraform Core is governed by the canonical guide at .github/CONTRIBUTING.md. This page summarizes the workflow and points to the documents that have the binding policy.

What this repo accepts

• Bug fixes with reproductions are nearly always welcome, especially fixes for crashes (fix panic for … is a common commit subject in recent history).
• Documentation, tooling, and lint improvements are welcome.
• Backend changes are graded by who maintains the backend. The Terraform team is not accepting new state-storage backends, and the AWS S3 / Azure backends see the most upstream care from the corresponding provider teams. See CODEOWNERS for the maintainer of each backend.
• Provisioners are deprecated (chef, salt-masterless, puppet, habitat). The team will not accept PRs that extend them.
• Language features and graph-engine changes are the most expensive area to land. The team strongly prefers a design discussion (issue first) before any code lands.

The PR lifecycle in two screens

1. Open an issue (or comment on an existing one) describing the change.
2. Get a "go ahead" from a core team member; for non-trivial work this is required for the PR to be reviewed.
3. Implement on a branch, run the lint + test commands documented in getting started.
4. Add a changie entry if your change is user-facing (see below).
5. Open the PR. The CI checks include unit tests, format/lint checks, the changelog check, and the CLA-signing bot.
6. Reviewers iterate; the contributor is expected to drive the PR to a mergeable state.
7. A team member merges. Backports happen via *-backport labels.

For the canonical version of all of this, read .github/CONTRIBUTING.md.

Changelog entries (changie)

User-facing PRs need a change file. The tooling is changie, run via npx:

npx changie new

The interactive prompt asks for a kind (NEW FEATURES, ENHANCEMENTS, BUG FIXES, NOTES, UPGRADE NOTES, BREAKING CHANGES), a one-line description, and a PR/issue number. The result is a YAML file under .changes/v1.XX/. The version directory must match the version in version/VERSION on main.

If your change is not user-facing, label the PR no-changelog-needed instead.

Backports

Patch releases pick changes from main into release branches. Tag the PR with the appropriate 1.XX-backport label(s) (see the labels list) and a maintainer will arrange the backport. Backport changie entries go in .changes/v1.XX/ of the earliest version being backported into.

AI-assisted contributions

The contribution guide includes a Generative AI usage policy. Disclose AI involvement in your PR description, retain ownership of the change, and prefix LLM-agent PR titles with 🤖🤖🤖 for expedited triage.

Where to look in this wiki next

• Development workflow — branch, build, test, fmt, vet, PR.
• Testing — unit, integration, acceptance, e2e, the terraform test framework.
• Debugging — TF_LOG, panics, plugin reattach, common pitfalls.
• Patterns and conventions — tfdiags, cty.Value, error wrapping, view layer.
• Tooling — what's in scripts/ and tools/, the protobuf wrapper, autocomplete install.