Skip to content

Contributing

This section provides guidance on how to contribute to the Kerko project.

Reporting issues

Before reporting an issue, please consider the following guidelines:

  • Try to identify whether the issue belongs to Kerko or to KerkoApp. Then submit the issue to the proper issue tracker, either Kerko's, or KerkoApp's.
  • Search existing issues, in case the same issue has already been reported or even fixed in the repository.
  • Describe what happened when you experienced the issue. Include the full traceback if an exception was raised.
  • Describe what you expected to happen.
  • If possible, include a minimal reproducible example to help others identify the issue.

Making code changes

Clone the Kerko repository into a local directory. Set up a virtual environment, then install that local version of Kerko in the virtual environment, including development and testing dependencies by running the following command from Kerko's root directory, i.e., where setup.cfg resides:

pip install -e .[dev,docs,tests]

Running the tests

To run the test suite:

python -m unittest

To check code coverage as well, use these commands instead:

coverage run -m unittest
coverage report

To run the full test suite under different environments (using the various Python interpreters available on your machine):

tox

Note

Test coverage is still low at the moment. You are welcome to contribute new tests!

Running the pre-commit hooks

Pre-commit checks should be performed automatically whenever you perform a git commit. If you wish to run the checks manually, use this command:

pre-commit run --all-files

Working on the documentation

To start a local live-reloading documentation server:

mkdocs serve

Then view the documentation in your browser at http://localhost:8000/.

Building the distribution package

When building the distribution package, a version number is dynamically extracted from the Git repository. For an official release, the Git head revision must be tagged prior to building the distribution package. When the revision is not tagged, a dev version number gets derived from the branch's most recent tag, with a suffix appended.

To check the version number that will be generated:

hatch version

To build the distribution package in sdist and wheel formats:

hatch build

Submitting code changes

Pull requests may be submitted against Kerko's repository. Please consider the following guidelines:

  • Before submitting, run the tests and make sure they pass. Add tests relevant to your change (those should fail if ran without your patch).
  • Use Ruff to format Python code.
  • If a Jinja2 template represents a page fragment or a collection of macros, prefix its file name with the underscore character.
  • Update the relevant sections of the documentation.
  • Include a string like "Fixes #123" in your commit message (where 123 is the issue you fixed). See Closing issues using keywords.

Submitting a translation

Some guidelines:

  • The PO file encoding must be UTF-8.
  • The header of the PO file must be filled out appropriately.
  • All messages of the PO file must be translated.

Please submit your translation as a pull request against the proper repository, either Kerko's, or KerkoApp's, or by e-mail, with the PO file included as an attachment (do not copy the PO file's content into an e-mail's body, since that could introduce formatting or encoding issues).

Supporting the project

Nurturing an open source project, following up on issues and helping others in working with the system is a lot of work. Hiring the original developers of Kerko can help make the project sustainable. It is the best way to ensure continued support and development of the project.

If you need professional support related to Kerko, have requirements not currently implemented in Kerko, want to make sure that some Kerko issue important to you gets resolved, or if you just like our work and would like to hire us for an unrelated project, please e-mail us.