Skip to content

CONTRIBUTING.rst

Latest commit

 

History

History
134 lines (86 loc) · 3.59 KB

CONTRIBUTING.rst

File metadata and controls

134 lines (86 loc) · 3.59 KB
Raw

Contributing

Troposphere and CloudFormation open up many possibilities, and we're open to any contributions that expand the flexibility of this project within its overall mission.

To contribute, you'll need Python 3.8+ and uv installed. Dependencies are managed via pyproject.toml.

Setup

uv sync
uv tool install pre-commit
# Optionally install git pre-commit hook:
pre-commit install

Using direnv, enable uv's virtual environment in your shell:

# .envrc
unset VIRTUAL_ENV
uv sync --locked
PATH_add .venv/bin

direnv allow

Sandbox Account for Testing

For sandbox testing instructions, see AGENTS.md in the repository root.

The short version: authenticate to your sandbox AWS account, then use the .venv/bin/aws CLI to create and update CloudFormation stacks.

source ~/.sandbox-aws-env
export AWS_DEFAULT_REGION=us-east-1
.venv/bin/aws sts get-caller-identity

See AGENTS.md for full stack creation and update examples.

Check Code Formatting

If you have the pre-commit hook installed per the above, code formatting will be checked automatically with each commit. You can optionally run all checks manually as well:

pre-commit run --all-files

Compile YAML Templates

make

This generates four templates in content/:

  • eks-no-nat.yaml — EKS without NAT gateway
  • eks-nat.yaml — EKS with NAT gateway
  • gc-no-nat.yaml — EKS on GovCloud without NAT gateway
  • gc-nat.yaml — EKS on GovCloud with NAT gateway

All templates must stay under 51,200 bytes.

Building the documentation

cd docs
make html

The docs will be available in the docs/_build/html/ directory.

Submitting Pull Requests

Please follow these basic steps to simplify pull request reviews.

  • Please rebase your branch against the current main branch
  • Please ensure pre-commit checks and make (see above) succeed before submitting a PR
  • Make reference to possible issues on PR comment

Submitting bug reports

  • Please include the exact filename of the template used
  • Please include any and all error messages generated by AWS

Release Process

  • Merge any PRs targeted for the release into the main branch.

  • Write release notes in the changelog, including:

    • links to PRs as appropriate
    • credit for outside contributors
    • a link (at the bottom of the file) to the listing page in the aws-web-stacks bucket

    It may help to view the changes since the last release:

    git diff -r v2.0.0

  • Tag the release in Git and push it to GitHub, e.g.:

    git checkout main && git pull
git tag -a v3.0.0 -m "v3.0.0"
git push origin v3.0.0

  • After pushing a version tag, Actions will:

    • create a release on GitHub
    • build the template YAML files
    • add the templates as an asset to the release
    • upload the templates to S3

    The current, stable (unversioned) releases will be overwritten, and a copy of the release will be archived to a folder named for the version in the S3 bucket.

  • Navigate to the Releases tab in GitHub and edit the release for the tag just pushed to include a copy of the release notes.