This page provides procedures and guidelines for developing and contributing to Kafkit.
Scope of contributions#
Kafkit is an open source package, meaning that you can contribute to Kafkit itself, or fork Kafkit for your own purposes.
Since Kafkit is intended for internal use by Rubin Observatory, community contributions can only be accepted if they align with Rubin Observatory’s aims. For that reason, it’s a good idea to propose changes with a new GitHub issue before investing time in making a pull request.
Kafkit is developed by the LSST SQuaRE team.
Setting up a local development environment#
To develop Kafkit, create a virtual environment with your method of choice (like virtualenvwrapper) and then clone or fork, and install:
git clone https://github.com/lsst-sqre/kafkit.git cd kafkit make init
This init step does three things:
Installs Kafkit in an editable mode with its “dev” extra that includes test and documentation dependencies.
Installs pre-commit and tox.
Installs the pre-commit hooks.
The pre-commit hooks, which are automatically installed by running the make init command on set up, ensure that files are valid and properly formatted. Some pre-commit hooks automatically reformat code:
Automatically fixes common issues in code and sorts imports.
Automatically formats Python code.
Automatically formats Python code in reStructuredText documentation and docstrings.
When these hooks fail, your Git commit will be aborted. To proceed, stage the new modifications and proceed with your Git commit.
One way to test the library is by running pytest from the root of the source repository:
You can also run tox, which tests the library the same way that the CI workflow does:
To see a listing of test environments, run:
Documentation is built with Sphinx:
tox run -e docs
The build documentation is located in the
Updating the change log#
Each pull request should update the change log (
The change log is maintained with scriv.
To create a new change log fragment, run:
This creates a new file in the
Edit this file to describe the changes in the pull request.
If sections don’t apply to the change you can delete them.
Document the Python API with numpydoc-formatted docstrings. See the LSST DM Docstring Style Guide.
Follow the LSST DM ReStructuredTextStyle Guide. In particular, ensure that prose is written one-sentence-per-line for better Git diffs.