Introduction
Terraform is a complex tool where even simple changes can have a serious impact on other areas of the code. The Terraform team takes stability seriously and appreciates the responsibility of maintaining software for a globally diverse community that relies on Terraform for workflows of all sizes and criticality.All communication on GitHub, the community forum, and other HashiCorp-provided communication channels is subject to the HashiCorp community guidelines.
What is Terraform Core?
This repository contains Terraform core, which includes:- The command line interface (CLI)
- The main graph engine
- Core language features
How to Contribute
Report Bugs and Request Features
The most straightforward way to help is to file a feature request or bug report. Please use the appropriate issue template and fill in all requested information to maximize the team’s ability to act on your feedback.Make Code Contributions
If you want to implement a solution yourself:- Discuss first: Before writing code, discuss your proposed solution with the core team on the GitHub issue. This ensures your approach aligns with project goals and avoids unintended consequences.
-
Start small: New contributors should begin with:
- Documentation improvements (can be done entirely in GitHub)
- Provider bug fixes (great first step in the ecosystem)
- Peripheral areas like functions or backends (less interaction with core)
- Avoid core changes initially: Changes to the graph engine and core language features are more difficult to contribute and require extensive discussion.
Areas of Special Concern
State Storage Backends
The Terraform team is not merging PRs for new state storage backends. The priority is finding maintainers for existing backends and removing those without maintainers. Backends fall into three categories:- Core team maintained: (e.g., HTTP) - Contributions unlikely to be accepted quickly
- HashiCorp provider teams: (e.g., AWS S3, Azure) - Reviewed irregularly, typically every few months
- Third-party maintained: (e.g., Postgres, COS) - Reviewed by maintainers, then merged by core team
Provisioners
Provisioners are often used in place of configuration management tools or custom providers. Tool-specific provisioners (chef, habitat, puppet, salt-masterless) are deprecated, and PRs for these areas will not be accepted.
From the Terraform documentation: Provisioners “add a considerable amount of complexity and uncertainty to Terraform usage” and should be used only as a last resort.
Proposing Changes
To be respectful of community contributors’ time:- Check for existing issues: Look for GitHub issues that already cover your bug or enhancement
- Start a discussion: Create or comment on an issue before investing development time
- Mention your intent: Let the team know you plan to implement the change
- Wait for feedback: The team will prioritize providing implementation guidance
Terraform does not currently have a formal process for reviewing outside proposals that significantly change Terraform’s workflow, primary usage patterns, or language. Start with an issue-based proposal for any substantial changes.
What to Expect
- Large proposals: For significant design changes, the team may not be able to give prompt feedback but is still interested in hearing about use cases
- Minor text changes: Comment and help text changes are not normally accepted
- Documentation and tests: Most changes require updates to both the test suite and documentation
Community Resources
- GitHub Issues: Report bugs and request features
- Community Forum: Ask questions and discuss
- CODEOWNERS: View maintainer assignments
Next Steps
Building from Source
Learn how to build Terraform from source code
Running Tests
Understand the testing requirements and workflows
Pull Request Guidelines
Learn the PR lifecycle and best practices
Bug Report Process
Understand how bug reports are triaged