Skip to content

Latest commit

 

History

History
96 lines (78 loc) · 4.32 KB

CONTRIBUTING.md

File metadata and controls

96 lines (78 loc) · 4.32 KB
Raw

Contributing

Thank you for your interest in contributing to MorphoClass!

Before you open an issue or start working on a pull request, please make sure to read the following guidelines.

  1. Creating Issues
  2. Working on the Code
  3. Creating Pull Requests
    1. Refer to an issue
    2. Add unit test
    3. Add type annotations
    4. Update dependencies
    5. Ensure all CI tests pass
    6. Get reviews and approval

Creating Issues

Before you submit an issue, please search our issue tracker to verify if any similar issue was raised in the past. Even if you cannot find a direct answer to your question, this can allow you to collect a list of related issues that you can link in your new issue.

Once you have verified that no similar issues exist yet, feel free to open a new issue.

Working on the Code

Our extended documentation on https://morphoclass.readthedocs.io has a dedicated installation section that will guide you through a development installation of MorphoClass. Please follow it to prepare your environment.

When working on the code please keep the following points in mind:

  • enable pre-commit (pre-commit install)
  • use black and isort to auto-format
    • pre-commit should normally do that for you automatically
    • check via tox -e lint (also runs flake8)
    • trigger formatting for all files via tox -e format
  • apply PEP8, check via tox -e lint
  • adding type annotations is preferred, use tox -e type for checking
  • re-generate the API docs for new modules via tox -e apidoc, check using tox -e apidoc-check
  • write unit tests, test by running pytest tests in the project root
  • add docstrings (NumPy style)
  • work on branches, don't push to main.

Creating Pull Requests

If you wish to contribute to the code base, opening a pull request on GitHub is the right thing to do!

Please read the following paragraphs to make sure that your work can be considered for a potential integration in our source code.

Refer to an issue

In general, every pull request should refer to a specific issue. If you would like to provide your contribution to an untracked issue, please create first an issue as explained here so that we can discuss the value of the proposed contribution and its implementation.

Add unit tests

Concerning CI tests, we are running various checks on linting, unit tests, docs, and packaging. If you are adding or modifying a functionality in the code, you are also expected to provide a unit test demonstrating and checking the new behavior.

Add type annotations

We are gradually introducing type annotations to our code, and our CI performs type checking with mypy. If your PR introduces a new function or heavily modifies an existing function, you should also add type annotations for such function.

Update dependencies

If your PR introduces a dependency on a new python package, this should be added to both the setup.py and the requirements.txt files.

Ensure all CI tests pass

We use GitHub Actions to run our CI tests. Once you open a PR, the workflow that runs all CI tests is automatically triggered. This workflow is also triggered every time a new commit is pushed to that PR branch. If you want to push a commit without triggering the CI tests (e.g. if a feature is still work in progress, and you want to save time), your commit message should include an appropriate label like [skip ci], [ci skip], [no ci] etc. (see here for the complete list).

All CI tests must pass before the pull request can be considered for review.

Get reviews and approval

Once you have satisfied all the previous points, feel free to open your pull request!

We will get back to you as soon as possible with comments and feedback in the format of pull request reviews. A positive review from one of the maintainers is required for the pull request to be merged into the master.