Contributing

In a nutshell, to contribute, follow this scenario:

  • Fork the repo in GitHub.

  • Clone the fork.

  • Check out a feature branch.

  • Implement the changes. * Lint with pre-commit run. * Test with pytest.

  • Sign off your commits.

  • Create a pull request.

  • Ensure all required checks pass.

  • Wait for a review by the project maintainers.

Git workflow

Kopf uses a Git Forking Workflow. This means all development should happen in individual forks, not in feature branches of the main repo.

The recommended setup:

  • Fork a repo on GitHub and clone the fork (not the original repo).

  • Configure the upstream remote in addition to origin:

git remote add upstream git@github.com:nolar/kopf.git
git fetch upstream

  • Sync your main branch with the upstream regularly:

git checkout main
git pull upstream main --ff
git push origin main

Work in feature branches of your fork, not in the upstream’s branches:

  • Create a feature branch in the fork:

git checkout -b feature-x
git push origin feature-x

  • Once the feature is ready, create a pull request from your fork to the main repo.

See also

Git conventions

The more rules you have, the less they are followed.

Kopf tries to avoid written rules and to follow human habits and intuitive expectations where possible. Therefore:

  • Write clear and explanatory commit messages and PR titles. Read How to Write a Git Commit Message for examples.

  • Avoid prefixes or suffixes in commit messages or PR titles for issues or change types. In general, keep the git log clean — it will later go into the changelogs.

  • Sign off your commits for DCO (see below).

No other rules.

DCO sign-off

All contributions (including pull requests) must agree to the Developer Certificate of Origin (DCO) version 1.1. This is the same one created and used by the Linux kernel developers, posted at http://developercertificate.org/.

This is a developer’s certification that they have the right to submit the patch for inclusion in the project.

Simply submitting a contribution implies this agreement. However, please include a “Signed-off-by” tag in every patch (this tag is a conventional way to confirm that you agree to the DCO).

The sign-off can be written manually or added with git commit -s. If you contribute often, you can automate this in Kopf’s repo with a Git hook.

Code style

Common sense is the best code formatter. Blend your code into the surrounding code’s style.

Kopf does not use and will never use strict code formatters (at least until they acquire common sense and context awareness). When in doubt, adhere to PEP 8 and the Google Python Style Guide.

The line length is 100 characters for code, 80 for docstrings and RST files. Long URLs can exceed this length.

For linting, minor code styling, import sorting, and layered module checks, run:

pre-commit run

Tests

If possible, run the unit-tests locally before submitting (this will save you some time, but is not mandatory):

pytest

If possible, run the functional tests with a realistic local cluster (for example, with k3s/k3d on macOS; Kind and Minikube are also fine):

brew install k3d
k3d cluster create
pytest --only-e2e

If that is not possible, create a draft PR instead, check the GitHub Actions results for unit and functional tests, fix as needed, and promote the draft PR to a full PR once everything is ready.

Reviews

If possible, reference the issue the PR addresses in the PR’s body. You can use one of the existing or closed issues that best matches your topic.

PRs can be reviewed and commented on by anyone, but can be approved only by the project maintainers.