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 commands from Kerko's root directory, i.e., where pyproject.toml resides:

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

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!

Updating the test fixtures

Some tests rely on fixtures that were generated from actual Zotero libraries. Each fixture is like a pre-built Kerko cache, allowing complex integration tests to run without any connection to Zotero.

The sources for those fixtures are publicly accessible Zotero group libraries. To rebuild the fixtures from zotero.org, use the following commands, replacing MY_ZOTERO_API_KEY with your actual Zotero API key:

export ZOTERO_API_KEY=MY_ZOTERO_API_KEY
make fixtures

For more details about the test fixtures, including the URLs of the source libraries:

make help

If you need to write new tests and need to add items to a source library, you could:

  1. Clone the source Zotero library;
  2. Add your new item(s);
  3. Temporarily set the clone's id for the fixture in the Makefile;
  4. Rebuild the fixture with make.

Any new test item must have a line in the form of KerkoTestID: MY-UNIQUE-ID in its Extra field, where MY-UNIQUE-ID is a unique key for this item. Any test must use this key wherever a Zotero item ID would normally be used. This way, the test will still pass even if the item is copied into a different library and has gotten a different item ID.

For examples of such tests, look for test cases that inherit SyncIndexTestCase.

Once your tests are implemented, we will be able to copy your new item(s) into the original fixture library, update the fixtures, and the tests will pass.

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.