How to Contribute
We'd love to accept your patches and contributions to this project. There are just a few small guidelines you need to follow.
Setting up environment
We highly recommend that you create a dedicated Python environment for Kapitan. There are multiple solutions:
Once you've done it, please install all Kapitan's dependencies:
python3 -m venv env source env/bin/activate pip3 install black # required for `make test_formatting` pip3 install -r requirements.txt
Because we are using a pinned version of reclass which is added as a submodule into Kapitan's repository, you need to pull it separately by executing the command below:
git submodule update --init
Troubleshoot pip install errors
Check if gcc is installed:
brew install gcc@5
make test to run all tests. If you modify anything in the
make sure you replicate the compiled result of that in
If you add new features, run
make test_coverage && make test_formatting to make sure the
test coverage remains at current or better levels and that code formatting is applied.
If you would like to evaluate your changes by running your version of Kapitan, you can do
that by running
bin/kapitan from this repository or even setting an alias to it.
python3 -m unittest tests/test_vault_transit.py
To make sure you adhere to the Style Guide for Python (PEP8)
Python Black is used to apply the formatting so make sure you have it installed with
pip3 install black.
Apply via Git hook
pip3 install pre-committo install precommit framework.
- In the Kapitan root directory, run
- Git add/commit any changed files you want.
make format_codestyle before submitting.
- Create a branch named
v0.*.*-rc.*if you want pre-release versions to be uploaded.
- Update CHANGELOG.md with the release changes.
- Once reviewed and merged, Github Actions will auto-release.
- The merge has to happen with a merge commit not with squash/rebase so that the commit message still mentions
Updating gh-pages docs
We use mkdocs to generate our gh-pages from
.md files under docs/ folder.
Updating our gh-pages is therefore a two-step process.
1. Update the
Submit a PR for our master branch that updates the
.md file(s). Test how the changes would look like when deployed to gh-pages by serving it on localhost:
2. Submit a PR for gh-pages branch to deploy the update
Once the above PR has been merged, use
mkdocs gh-deploy command to push the commit that updates the site content to your own gh-pages branch. Make sure that you already have this gh-pages branch in your fork that is up-to-date with our gh-pages branch such that the two branches share the commit history (otherwise Github would not allow PRs to be created).
# locally, on master branch (which has your updated docs) COMMIT_MSG="your commit message to replace" make mkdocs_gh_deploy
After it's pushed, create a PR that targets our gh-pages branch from your gh-pages branch.
Packaging extra resources in python package
To package any extra resources/files in the pip package, make sure you modify both
Contributor License Agreement
Contributions to this project must be accompanied by a Contributor License Agreement. You (or your employer) retain the copyright to your contribution, this simply gives us permission to use and redistribute your contributions as part of the project. Head over to https://cla.developers.google.com/ to see your current agreements on file or to sign a new one.
You generally only need to submit a CLA once, so if you've already submitted one (even if it was for a different project), you probably don't need to do it again.