Contributing#

We promote a number of packages to open-source, and welcome contributions from the community. Explore the page to see what we have available, and feel free to fork and submit pull requests for any changes you think would be useful.

Documentation#

If you were reading the documentation, and spotted a mistake, or something that could be improved, please fork the docs branch of the repository and create a pull request with your changes to the dev/docs branch. We will review your changes and merge them into the documentation.

As part of documentation is generated from docstrings, we also welcome improvements to the docstrings and interfaces that improve developer experience.

The documentation is built using Sphinx. To build the documentation locally, you will need to install the dependencies from requirements.dev.txt, and then run

rm -rf build-docs && sphinx-build docs build-docs

Warning

The branch dev/docs is not meant to be merged to any of upstream branches. It is used only for documentation purposes.

Git Workflow#

We use a dev/unstable branch for development. Or changes merge here first, and are then reviewed and merged into the dev/stable branch. After a period of working with dev version we conclude that release is indeed stable, we merge it into the main branch.

If you wish to contribute to the project, please fork the repository and create a pull request with your changes to the dev/unstable branch. We will review your changes and merge them.

We perform a couple of procedures to ensure that the code is of high quality:

Before merging into the dev/unstable branch, check your code with ruff linter. This will ensure that your code is formatted correctly, and that you have not introduced any errors. After installing dependencies from requirements.dev.txt, you can run ruff check malevich/ from the root of the repository.
When dealing with branches, we follow the following convention:
- If you are working on a new feature, create a branch with the name feature/<name>. These branches are merged into the dev/unstable branch. If someone else is working on the same feature, you can create a branch with the name feature/<name>-<username>.
- If you are fixing a bug, create a branch with the name fix/<name>. These branches are are merged into the dev/unstable branch. If someone else is working on the same bug, you can create a branch with the name fix/<name>-<username>. We hope that there were no bugs that will require multiple people to work on them at the same time, but stil…
- If you spot an issue that preventing you from using an important feature of Malevich package you can create a branch with the name hotfix/<name>. These branches are merged into the main branch directly after review yielding a new version immediately.
When dealing with commits, we follow the following convention for commit messages:

<type>: <message>

<longer message>

where type is one of:

add: A new feature
fix: A bug fix
docs: Documentation only changes
style: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
upd: A code change that neither fixes a bug nor adds a feature
misc: Other changes

If commit serve several purposes, you can use multiple types in the commit message. For example, if you are adding a new feature, but also fixing a bug, you can use the commit message:

add, fix: <message>

<longer message>

add: <message>; fix: <message>

<longer message>

Posting an issue#

If you have found a bug, or have a feature request, please post an issue on Github.

When posting an issue, it is helpful to include:

A description of the bug or feature request
A version of Malevich you are using
A minimal working example that reproduces the bug or describes the feature request
The content of ~/.malevich/logs folder (it will contain useful anonymous information about actions you have performed with Malevich)
The content of malevich.yaml file from the root of your project (if you have one)