Skip to content

Latest commit

 

History

History
84 lines (57 loc) · 4.06 KB

CONTRIBUTING.md

File metadata and controls

84 lines (57 loc) · 4.06 KB
Raw

Contribution Guidelines

Contributions to this module are very welcome! We follow a fairly standard pull request process for contributions, subject to the following guidelines:

  1. File a GitHub issue
  2. Update the examples and tests
  3. Update the code
  4. Update the documentation
  5. Create a pull request
  6. Merge and release

File a GitHub issue

Before starting any work, we recommend filing a GitHub issue in this repo. This is your chance to ask questions and get feedback from the maintainers and the community. If there is anything you're unsure about, just ask!

Update the examples and tests

We also recommend updating the examples/creating new examples before updating any code. This ensures the examples stay up to date and verify all the functionality in this module, including whatever new functionality you're adding in your contribution.

Examples are used as test data for terratest tests. Updating/writing new tests and executing them in your own AWS account would be helpful.

At least you should run terraform apply for all new or updated examples since some errors won't occur in the planning phase. This may create resources which cost money. Run terraform destroy to destroy those resources.

Update the code

At this point, make your code changes and use your updated or new example to verify that everything is working. As you work, keep in mind two things:

  1. Backwards compatibility
  2. Downtime

Please adhere to the Terraform module guidelines.

Backwards compatibility

Please make every effort to avoid unnecessary backwards incompatible changes. With Terraform code, this means:

  1. Do not delete, rename, or change the type of input variables.
  2. If you add an input variable, it should have a default.
  3. Do not delete, rename, or change the type of output variables.
  4. Do not delete or rename a module in the modules folder.

If a backwards incompatible change cannot be avoided, please make sure to call that out when you submit a pull request, explaining why the change is absolutely necessary.

Downtime

Bear in mind that the Terraform code in this module is used by real companies to run real infrastructure in production, and certain types of changes could cause downtime. For example, consider the following:

  1. If you rename a resource (e.g. aws_instance "foo" -> aws_instance "bar"), Terraform will see that as deleting the old resource and creating a new one.
  2. If you change certain attributes of a resource (e.g. the name of an aws_elb), the cloud provider (e.g. AWS) may treat that as an instruction to delete the old resource and a create a new one.

Deleting certain types of resources (e.g. virtual servers, load balancers) can cause downtime, so when making code changes, think carefully about how to avoid that. For example, can you avoid downtime by using create_before_destroy? Or via the terraform state command? If so, make sure to note this in our pull request. If downtime cannot be avoided, please make sure to call that out when you submit a pull request.

Update the documentation

Please update the documentation of the root and all affected nested modules. Version information will be updated by tooling.

Create a pull request

Create a pull request with your changes. Please make sure to include the following:

  1. A description of the change, including a link to your GitHub issue.
  2. Any notes on backwards incompatibility or downtime.

Merge and release

The maintainers for this repo will review your code and provide feedback. If everything looks good, they will merge the code and release a new version, which you'll be able to find in the releases page.