Skip to content

Latest commit

 

History

History
115 lines (79 loc) · 5.49 KB

CONTRIBUTING.md

File metadata and controls

115 lines (79 loc) · 5.49 KB
Raw

Contribution Guidelines

Contributions to this Package 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 documentation
  3. Update the tests
  4. Update the code
  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 before you sink a lot of time into writing (possibly the wrong) code. If there is anything you're unsure about, just ask!

Update the documentation

We recommend updating the documentation before updating any code (see Readme Driven Development). This ensures the documentation stays up to date and allows you to think through the problem at a high level before you get lost in the weeds of coding.

Update the tests

We also recommend updating the automated tests before updating any code (see Test Driven Development). That means you add or update a test case, verify that it's failing with a clear error message, and then make the code changes to get that test to pass. This ensures the tests stay up to date and verify all the functionality in this Module, including whatever new functionality you're adding in your contribution. Check out the tests folder for instructions on running the automated tests.

Update the code

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

  1. Backwards compatibility
  2. Downtime

Backwards compatibility

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

  1. Do not delete, rename, or change the type of input variables.
  2. If you add an input variable, set a default in values.yaml.
  3. Do not delete, rename, or change the type of output variables.
  4. Do not delete or rename a chart in the charts 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 Helm charts in this Module are used by real companies to run real infrastructure in production, and certain types of changes could cause downtime. If downtime cannot be avoided, please make sure to call that out when you submit a pull request.

Code style

We follow the official Chart best practices documented by the community. Please read through the guidelines if you have not already.

Additionally, Gruntwork has a few extra guidelines not stated in the best practices guide:

  • Chart values.yaml should separate required inputs from optional inputs. Required inputs should be documented as comments.
  • Provide example required inputs in a separate linter_values.yaml file so that helm lint can be used to lint the charts.
  • Any input value that is rendered directly in the yaml templates (using toYaml) should be explicitly called out in the values.yaml file.
  • Any input value that is a map should explicitly call out the expected fields. Additionally, the fields should be labeled by type and whether or not the value is required.
  • Any required input that is a map, or optional input that is a map with an empty default, should have an example in the comments.
  • Every chart should have both helm tests and terratests. The helm tests test if the chart came up successfully in an install, while the terratest is used for integration testing of the chart before releasing the chart.

Formatting and pre-commit hooks

You must run helm lint on the code before committing. You can configure your computer to do this automatically using pre-commit hooks managed using pre-commit:

  1. Install pre-commit. E.g.: brew install pre-commit.
  2. Install the hooks: pre-commit install.
  3. Make sure you have the helm client installed. See the official docs for instructions.

Now write your code, and every time you commit, helm lint will be run on the charts that you modify.

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. The output of your automated test run, preferably in a GitHub Gist. We cannot run automated tests for pull requests automatically due to security concerns, so we need you to manually provide this test output so we can verify that everything is working.
  3. 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.