Skip to content

Latest commit

 

History

History
220 lines (139 loc) · 7.89 KB

CONTRIBUTING.rst

File metadata and controls

220 lines (139 loc) · 7.89 KB
Raw

Contributing to Kornia

Welcome !! This is the Kornia library contributors corner. If you are reading this, it means that you have interest in Differentiable Computer Vision, and willing to contribute to the project.

Everyone is welcomed to get involved with the project. There are different ways in how you can put your two cents:

  1. Ask/Answer questions using the #kornia tag in PyTorch Discuss
    • Please, don't use GitHub issues for Q&A.
    • In case you are a developer and want to learn more about the PyTorch ecosystem, we suggest you to join the PyTorch slack. You can apply using this form: https://bit.ly/ptslack
  2. Report bugs through GitHub issues:
    • Do a quick search first to see whether others reported a similar issue.
    • In case you find an unreported bug, please open a new ticket.
    • Try to provide as much information as possible. Some tips:
      • Clear title and description of the issue.
      • Explain how to reproduce the error.
      • Report your packages versions to facilitate the task.
      • Try to include a code sample/test that raises the error.
  3. Fix a bug or develop a feature from the roadmap:
    • We will always have an open ticket showing the current roadmap.
    • Pick an unassigned feature (or potentially propose new one) or an open bug ticket.
    • Follow the instructions from Developing Kornia in order to setup your development environment and start coding.
    • Checkout our coding conventions. See more details below.
    • Run the test framework locally and make sure all works as expected before sending a pull request.
    • Open a Pull Request, get the green light from the CI and get your code merged.
  4. Donate resources to the project:
    • In case you are an organization/institution that want to give support, sponsor or just use the project, please contact us.
    • We are open to start any kind of collaboration and hear feedback from you.
    • We pretend to provide features on demand. Reach us !
    • Currently looking for some kind of server donation in order to test CUDA code. (Please contact us).

Developing Kornia

In order to start to develop, please follow the steps below:

  1. Uninstall all existing installs:
pip uninstall kornia
pip uninstall kornia  # run this command twice
  1. Clone a copy of Kornia from source:
git clone https://github.com/kornia/kornia.git
cd kornia
  1. Create a new branch with a meaningful name reflecting your contribution. See an example:
git checkout -b feat/foo_feature
# or
git checkout -b fix/bar_bug
  1. Assuming that you are on ubuntu 16.04, with nvidia-drivers installed. In bash, source the path.bash.inc script. This will install a local conda environment under ./.dev_env, which includes pytorch and some dependencies (no root required).
source ./path.bash.inc
python setup.py develop
python -c "import kornia; print(kornia.__version__)"

To install, or update the conda environment run setup_dev_env.sh

./setup_dev_env.sh

Coding Standards

This section provides general guidance for developing code for the project. The following rules will serve as guide in writing high-quality code that will allow us to scale the project and ensure that the code base remains readable and maintainable.

  • Use meaningful names for variables, functions and classes.

  • Write small incremental changes:

    • In order to have a linear and clean commits history, we recommend to commit each small change that you do to the source code.
    • Clear commit messages will help to understand the progress of your work.
    • Please, avoid pushing large files.

  • Add tests:

    • Tests are crucial and we expect you to write unit test for each of the functionalities that you implement. It is also a good idea to group the tests for functionalities
    class TestMyFunction:
    def test_smoke(self):
        # check defaults parameters, i/o shapes
        pass

    def test_feature_foo(self):
        # test basic functionality
        pass

     def test_feature_bar(self):
         # test another functionality
         pass

     def test_gradcheck(self):
         # test the functionality gradients
         pass

     def test_jit(self):
         #  test the functionality using jit modules
         pass
    • Tests should cover different devices (CPU and CUDA) and different input batch size. See an example:
    @pytest.mark.parametrize("device_type", ("cpu", "cuda"))
@pytest.mark.parametrize("batch_size", [1, 2, 5])
def test_smoke(batch_size, device_type):
    x = torch.rand(batch_size, 2, 3)
    x = x.to(torch.device(device_type))
    assert x.shape == (batch_size, 2, 3), x.shape

  • We give support to static type checker for Python >= 3.6

    • Please, read MyPy cheatsheet for Python 3.
    • It is recommended to use typing inside the function, when it would increase readability.
    • Always type function input and output, e.g.:
def homography_warp(patch_src: torch.Tensor,
                    dst_homo_src: torch.Tensor,
                    dsize: Tuple[int, int],
                    mode: str = 'bilinear',
                    padding_mode: str = 'zeros') -> torch.Tensor:
python_version: int = 3
print(f"This is an example to use Python {python_version}'s f-Strings")

  • Format your code:

    pre-commit install

  • Changes to PEP8:

    • Line length is 120 char.
    • W504 (line break after binary operator) is sometimes acceptable. E.g.
determinant = A[:, :, 0:1, 0:1] * A[:, :, 1:2, 1:2] -
              A[:, :, 0:1, 1:2] * A[:, :, 1:2, 0:1])
  • Using 3rd party libraries:

Pull Request

Once you finish implementing a feature or bug-fix, please send a Pull Request to https://github.com/kornia/kornia through the website.

If you are not familiar with creating a Pull Request, here are some guides:

Once your pull request is created, our continuous build system will check your pull request. Continuous build will test that:

  • pytest all tests pass.
  • flake8 accepts the code style (our guidelines are based on PEP8).
  • mypy type checks the Python code.
  • The docs can be generated successfully
  • Test coverage remains high. Please add unit tests so we maintain our code coverage.

If your code fails one of these checks, you will be expected to fix your pull request before it is considered.

Unit testing

To run the test suite locally, make sure that you have activated the conda environment, then:

make test

Licence

By contributing to the project, you agree that your contributions will be licensed under the LICENSE file in the root directory of this source tree.