Welcome to the WEBKNOSSOS-libs contributing guide
Thank you for taking the time to contribute to this project! The following is a set of guidelines for contributing to the different WEBKNOSSOS related Python libraries, which are part of the WEBKNOSSOS-libs repository on GitHub. These are mostly guidelines, not rules. Use your best judgment, and feel free to propose changes to this document in a pull request.
Code of Conduct
How can I help?
We welcome community feedback and contributions! We are happy to have
- general feedback, observations and questions on the image.sc forum,
- feature suggestions and bug reports as issues on GitHub,
- documentation, examples and code contributions as pull requests on GitHub.
Feedback, Observations and Questions
We'd love to hear your feedback on the WEBKNOSSOS Python libraries! We're also interested in hearing if these tools don't work for your usecase, or if you have questions regarding their usage.
Please leave a message on the image.sc forum
webknossos tag to enable public communication on those topics.
If you prefer to share information only with the WEBKNOSSOS team, please write an email
to firstname.lastname@example.org. For commercial support please
reach out to scalable minds.
Issues: Feature Suggestions and Bug Reports
We track feature requests and bug reports in the WEBKNOSSOS-libs repository issues. Before opening a new issue, please do a quick search of existing issues to make sure your suggestion hasn’t already been added. If your issue doesn’t already exist, and you’re ready to create a new one, make sure to state what you would like to implement, improve or bugfix. Please use one of the provided templates to make this process easier for you.
Report a Bug
When you find a bug, please double-check if an issue for the same bug exists already. If that's not the case, please verify in the documentation that you use the API as intended. If that's the case, please add an issue using the bug report template.
Suggest a New Feature
If you are missing a feature to support your use-case, please consider the following points:
- Please verify if this feature is directly related to WEBKNOSSOS. Does it belong into the WEBKNOSSOS Python libraries?
- Double-check if an issue for this feature exists already. If there is one with a very similar scope, please considering commenting there.
- If possible, consider how the implementation might look like (e.g. how would the public API change), as well as how this could be tested and presented in the examples.
Then, please add an issue using the feature suggestion template.
Pull Requests: Docs and Code Contributions
This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla-assistant.io/scalableminds/webknossos-libs.
When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once using our CLA.
For larger features and changes, we prefer that you open a new issue before creating a pull request. Please include the following in your pull request:
- The pull request description should explain what you've done.
- Add tests for the new features.
- Comply with the coding styles.
- Adapt or add the documentation.
- Consider enhancing the examples.
The specific coding styles, test frameworks and documentation setup of WEBKNOSSOS-libs are described in the following sections:
The WEBKNOSSOS-libs repository is structured as a mono-repo, containing multiple packages:
docs, see below for Documentation)
See below for specifics of the different packages. Let's have a look at the common tooling first:
- poetry is used for dependency management and publishing.
poetry install --all-extrasin each package folder to install all dependencies for development. By default, this creates a virtual environment for each package. To run commands inside this package, prefix them with
poetry run, e.g.
poetry run python myscript.py, or enter the virtual environment with
poetry shell. The creation of a separate environment can be disabled (e.g. if you want to manage this manually), see here for details. To install the preferred version for this repository, run
pip install -f requirements.txt
To install the dependencies for all sub-projects, run
- Tooling we use across the sub-projects to enforce coding styles and tests:
./format.sh: black and isort
./test.sh: pytest and custom scripts
Those are also accessible via make commands from the top-level directory, running the respective scripts for each sub-project
make lint, …
Internal workflows for scalable minds:
- CI: We use continuous integration with github actions,
please see the
CIworkflow for details.
- Releases are triggered via the
Automatic releasegithub action, using the
Run workflowbutton in the topright corner. This updates the changelog and pushes a new tag, which triggers another CI run building and publishing the package.
webknossos folder contains examples, which are not part of the package, but are tested via
tests/test_examples.py and added to the documentation (see
The tests also contain functionality for the WEBKNOSSOS client. There a two modes to run the tests:
./test.sh --refresh-snapshots, sending network requests to a WEBKNOSSOS instance: This expects a local WEBKNOSSOS setup with specific test data, which is shipped with WEBKNOSSOS. If you're starting and running WEBKNOSSOS manually, please use port 9000 (the default) and run the
tools/postgres/prepareTestDb.shscript in the WEBKNOSSOS repository (⚠️ this overwrites your local WEBKNOSSOS database). Alternatively, a docker-compose setup is started automatically for the tests, see
tests/docker-compose.ymlfor details. The network requests & response are recorded as "cassettes" by vcr.py, see next point:
./test.shreplays responses from previous network snapshots using vcr.py via pytest-recording. No additional network requests are allowed in this mode.
./test.sh --store-durations updates the durations for
which is used in the CI to split the tests for different runners.
The code under
webknossos/client/_generated is auto-generated! Please don't adapt anything in the
generated folder manually, but re-run the code generation.
To re-generate the code, run
For testing the
slurm setup a docker-compose setup is available. Please see the respective Readme for details.
For testing the
kubernetes setup, we recommend a Kubernetes-in-Docker setup.
We render a common documentation for WEBKNOSSOS itself and WEBKNOSSOS-libs from this repository using mkdocs. Source-files for the documentation are stored at
docs/src/webknossos: Server & Website documentation, linked from the webknossos repository (must be available under
docs/wk-repo, see below).
docs/src/api: Generated using pdoc from Python docstrings.
docs/src/webknossos-py: Documentation for the Python Package
The structure of the documentation page is given by
To generate the documentation locally, clone or link the WEBKNOSSOS repository to
docs/wk-repo first and then start the documentation server
git clone --depth 1 email@example.com:scalableminds/webknossos.git docs/wk-repo docs/generate.sh
You can use
docs/generate.shfor hot-reloading markdown docs,
docs/generate.sh --apito get the pure pdoc documentation, hot-reloading docstrings,
docs/generate.sh --persistto persist the docs under docs/out.