Contributing to Sceptre

Thanks for your interest in Sceptre! We greatly appreciate any contributions to the project.

Code of Conduct

This project adheres to the Contributor Covenant code of conduct. By participating, you are expected to uphold this code. Please report unacceptable behaviour to the Sceptre github discussion.

How to Contribute

Report Bugs

Before submitting a bug, please check our issues page and discussion board to see if it's already been reported.

When reporting a bug, fill out the required template, and please include as much detail as possible as it helps us resolve issues faster.

Enhancement Proposal

Enhancement proposals should:

Use a descriptive title.
Provide a step-by-step description of the suggested enhancement.
Provide specific examples to demonstrate the steps.
Describe the current behaviour and explain which behaviour you expected to see instead.
Keep the scope as narrow as possible, to make it easier to implement.

Contributing Code

Contributions should be made in response to a particular GitHub Issue. We find it easier to review code if we've already discussed what it should do, and assessed if it fits with the wider codebase.

Beginner friendly issues are marked with the beginner friendly tag. We'll endeavour to write clear instructions on what we want to do, why we want to do it, and roughly how to do it. Feel free to ask us any questions that may arise.

A good pull request:

Is clear.
Works across all supported version of Python.
Complies with the existing codebase style (pre-commit)
Includes docstrings and comments for unintuitive sections of code.
Includes documentation for new features.
Includes tests cases that demonstrates the previous flaw that now passes with the included patch, or demonstrates the newly added feature.
New code should have 100% test coverage. The build will fail if overall code-coverage falls below 92%.
Is appropriately licensed (Apache 2.0).

Please keep in mind:

The benefit of contribution must be compared against the cost of maintaining the feature, as maintenance burden of new contributions are usually put on the maintainers of the project.

Dependency Management

Poetry is the tool that is used for dependency management, versioning and deployment management to pypi. Please install poetry and execute commands from the poetry environment.

Get Started

Fork the sceptre repository on GitHub.
Clone your fork locally

$ git clone git@github.org:<github_username>/sceptre.git

Install Sceptre for development (we recommend you use a virtual environment)

$ poetry install --all-extras -v

Create a branch for local development:

$ git checkout -b <branch-name>

When you're done making changes, check that your changes pass linting, unit tests and have sufficient coverage and integration tests pass.
Make sure the changes comply with the pull request guidelines in the section on Contributing Code.
Commit and push your changes.

Commit messages should follow these guidelines

Use the following commit message format [Resolves #issue_number] Short description of change.

e.g. [Resolves #123] Fix description of resolver syntax in documentation
Submit a pull request through the GitHub website.

Linting

As a pre-deployment step we syntatically validate files with pre-commit.

Run poetry run pre-commit install to setup the git hooks. Once configured the pre-commit linters will automatically run on every git commit. Alternatively you can manually execute the validations by running

$ poetry run pre-commit run --all-files

The CI for pre-commit has been offloaded to pre-commit.ci The configuration is in the pre-commit-config.yaml file.

Unit Tests

Sceptre aims to be compatible with Python 3, please run unit test against all supported versions.

Tox is used to execute tests against multiple python versions inside of poetry virtual environments.

$ poetry run tox

To run a specific test file:

$ poetry run pytest -ssv <test-file>.py

Or to run a specific test in that file:

$ poetry run pytest -ssv <test-file>.py::<unit-test-class>::<test-case>

Documentation

Sceptre uses Sphinx to generate documentation in HTML format.

To build the documentation locally:

  $ poetry run make html --directory docs

Note: The generated documentation files are in docs/_build/html

The CI for Sceptre docs have been offloaded to readthedocs.org. It is managed by the .readthedocs.yaml configuration file which builds the docs on every change and publishes them to sceptre.readthedocs.io.

The docs.sceptre-project.org domain is setup to be the main website for Sceptre docs.

Integration Tests

If you haven't setup your local environment or personal Github action to run integration tests then follow these steps:

To run on Github action (please do this before submitting your PR so we can see that your tests are passing):

Login to your Github Account.
On your Sceptre fork goto repositories -> sceptre -> settings -> enable "Allow all actions and reusable workflows"
Setup Github OIDC to allow access to your AWS account or add your Access Key ID and Secret Access Key that is associated with an IAM User from your AWS account. The IAM User will require "Full" permissions for CloudFormation and S3 and Write permissions for STS (AssumeRole). For an example please take a look at the Sceptre CI service user policy

Once you have set up Github action any time you commit to a branch in your fork all tests will be run, including integration tests.

You can also (optionally) run the integration tests locally, which is quicker during development.

To run integration tests locally

pip install awscli
Setup AWS CLI Environment variables to work with an AWS account that you have access to. You can use the same user or role that you use for Github actions.

run all tests

$ AWS_DEFAULT_REGION=eu-west-1 poetry run behave integration-tests/features --junit --junit-directory build/behave

Note: All integration tests are set up to run in eu-west-* region. If you prefer to run in a different region, you must update the region in each test before running it:

$ grep -r eu-west integration-tests

Edit the files.

$ AWS_PROFILE=<your-profile> AWS_DEFAULT_REGION=<your-preferred-default-region> poetry run behave integration-tests/features --junit --junit-directory build/behave

run a specific feature

$ poetry run behave integration-tests --include <feature-file>

run a specific scenario

$ poetry run behave integration-tests -n "<scenario-name>"

Add a debugger

To add a Python debugger like ipdb or pdb++ using poetry:

$ poetry run pip install ipdb
$ poetry run pip install pdbpp

Credits

This document took inspiration from the CONTRIBUTING files of the Atom and Boto3 projects.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!