Thank you for investing your time and energy by contributing to our project: please ensure you are familiar with the HashiCorp Code of Conduct.
This provider is a HashiCorp utility provider, which means any bug fix and feature has to be considered in the context of the thousands/millions of configurations in which this provider is used. This is great as your contribution can have a big positive impact, but we have to assess potential negative impact too (e.g. breaking existing configurations). Stability over features.
To provide some safety to the wider provider ecosystem, we strictly follow semantic versioning and HashiCorp's own versioning specification. Any changes that could be considered as breaking will only be included as part of a major release. In case multiple breaking changes need to happen, we will group them in the next upcoming major release.
For questions, curiosity, or if still unsure what you are dealing with, please see the HashiCorp Terraform Providers Discuss forum.
Please disclose security vulnerabilities responsibly by following the HashiCorp Vulnerability Reporting guidelines.
We welcome issues of all kinds including feature requests, bug reports or documentation suggestions. Below are guidelines for well-formed issues of each type.
- Test against latest release: Make sure you test against the latest available version of Terraform and the provider. It is possible we may have already fixed the bug you're experiencing.
- Search for duplicates: It's helpful to keep bug reports consolidated to one thread, so do a quick search
on existing bug reports to check if anybody else has reported the same thing.
You can scope searches by the label
bugto help narrow things down. - Include steps to reproduce: Provide steps to reproduce the issue, along with code examples and/or real code, so we can try to reproduce it. Without this, it makes it much harder (sometimes impossible) to fix the issue.
- Search for possible duplicate requests: It's helpful to keep requests consolidated to one thread,
so do a quick search on existing requests to check if anybody else has reported the same thing.
You can scope searches by the label
enhancementto help narrow things down. - Include a use case description: In addition to describing the behavior of the feature you'd like to see added, it's helpful to also make a case for why the feature would be important and how it would benefit the provider and, potentially, the wider Terraform ecosystem.
Thank you for contributing!
We are happy to review pull requests without associated issues, but we highly recommend starting by describing and discussing your problem or feature and attaching use cases to an issue first before raising a pull request.
- Early validation of idea and implementation plan: provider development is complicated enough that there are often several ways to implement something, each of which has different implications and tradeoffs. Working through a plan of attack with the team before you dive into implementation will help ensure that you're working in the right direction.
- Tests: It may go without saying, but every new patch should be covered by tests wherever possible. For bug-fixes, tests to prove the fix is valid. For features, tests to exercise the new code paths.
- Go Modules: We use Go Modules to manage and version our dependencies.
Please make sure that you reflect dependency changes in your pull requests appropriately
(e.g.
go get,go mod tidyor other commands). Refer to the dependency updates section for more information about how this project maintains existing dependencies. - Changelog: Refer to the changelog section for more information about how to create changelog entries.
- License Headers: All source code requires a license header at the top of the file, refer to License Headers for information on how to autogenerate these headers.
Dependency management is performed by Dependabot. Where possible, dependency updates should occur through that system to ensure all Go module files are appropriately updated and to prevent duplicated effort of concurrent update submissions. Once available, updates are expected to be verified and merged to prevent latent technical debt.
HashiCorp’s open-source projects have always maintained user-friendly, readable CHANGELOGs that allow
practitioners and developers to tell at a glance whether a release should have any effect on them,
and to gauge the risk of an upgrade.
We follow Terraform Plugin changelog specifications.
This provider uses the Changie automation tool for changelog automation.
To add a new entry to the CHANGELOG install Changie using the following instructions
and run
changie newthen choose a kind of change corresponding to the Terraform Plugin changelog categories
and then fill out the body following the entry format. Changie will then prompt for a Github issue or pull request number.
Repeat this process for any additional changes. The .yaml files created in the .changes/unreleased folder
should be pushed the repository along with any code changes.
Entries that are specific to resources or data sources, they should look like:
* resource/RESOURCE_NAME: ENTRY DESCRIPTION
* data-source/DATA-SOURCE_NAME: ENTRY DESCRIPTIONThe CHANGELOG is intended to show developer-impacting changes to the codebase for a particular version.
If every change or commit to the code resulted in an entry, the CHANGELOG would become less useful for developers.
The lists below are general guidelines to decide whether a change should have an entry.
- Documentation updates
- Testing updates
- Code refactoring
- Dependency updates: If the update contains relevant bug fixes or enhancements that affect developers, those should be called out.
- Major features
- Bug fixes
- Enhancements
- Deprecations
- Breaking changes and removals
All source code files (excluding autogenerated files like go.mod, prose, and files excluded in .copywrite.hcl) must have a license header at the top.
This can be autogenerated by running make generate or running go generate ./... in the /tools directory.