Contributing to MONAI Deploy App SDK¶
Welcome to Project MONAI Deploy App SDK! We’re excited you’re here and want to contribute. This documentation is intended for individuals and institutions interested in contributing to MONAI Deploy App SDK. MONAI Deploy App SDK is an open-source project and, as such, its success relies on its community of contributors willing to keep improving it. Your contribution will be a valued addition to the code base; we simply ask that you read this page and understand our contribution process, whether you are a seasoned open-source contributor or whether you are a first-time contributor.
Communicate with us¶
We are happy to talk with you about your needs for MONAI Deploy App SDK and your ideas for contributing to the project. One way to do this is to create an issue discussing your thoughts. It might be that a very similar feature is under development or already exists, so an issue is a great starting point. If you are looking for an issue to resolve that will help Project MONAI Deploy App SDK, see the good first issue and Contribution wanted labels.
The contribution process¶
Pull request early
We encourage you to create pull requests early. It helps us track the contributions under development, whether they are ready to be merged or not. Change your pull request’s title, to begin with
[WIP] and/or create a draft pull request until it is ready for formal review.
Please note that, as per PyTorch, MONAI Deploy App SDK uses American English spelling. This means classes and variables should be: normalize, visualize, colo~~u~~r, etc.
For local development, please execute the following command:
./run setup # '-h' for help
This will set up the development environment, installing necessary packages.
Preparing pull requests¶
To ensure the code quality, MONAI Deploy App SDK relies on several linting tools (flake8 and its plugins, black, isort), static type analysis tools (mypy, pytype), as well as a set of unit/integration/system tests.
This section highlights all the necessary preparation steps required before sending a pull request. To collaborate efficiently, please read through this section and follow them.
Checking the coding style¶
Coding style is checked and enforced by flake8, black, and isort, using a flake8 configuration similar to PyTorch’s. Before submitting a pull request, we recommend that all linting should pass, by running the following command locally:
# Setup development environment ./run setup # Run the linting and type checking tools ./run check --codeformat # or -f # Try to fix the coding style errors automatically ./run check --autofix # Show help ./run check --help
License information: all source code files should start with this paragraph:
# Copyright 2021 MONAI Consortium # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. # You may obtain a copy of the License at # http://www.apache.org/licenses/LICENSE-2.0 # Unless required by applicable law or agreed to in writing, software # distributed under the License is distributed on an "AS IS" BASIS, # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License.
If you intend for any variables/functions/classes to be available outside of the file with the edited functionality, then:
Create or append to the
__all__variable (in the file in which functionality has been added), and
Add to the
MONAI Deploy App SDK tests are located under
tests/ (it has
The unit test’s file name currently follows
test_[module_name]_dist.pysubset of unit tests requires a distributed environment to verify the module with distributed GPU-based computation.
The integration test’s file name follows
A bash script (
run) is provided to run all tests locally.
./run test -h to see all options.
To run a particular test, for example,
./run pytest tests/unit/test_sizeutil.py
Before submitting a pull request, we recommend that all linting and tests should pass, by running the following command locally:
./run check -f ./run test
or (for new features that would not break existing functionality):
./run check -f ./run test all unit # execute unit tests only
If it’s not tested, it’s broken
All new functionality should be accompanied by an appropriate set of tests. MONAI Deploy App SDK functionality has plenty of unit tests from which you can draw inspiration, and you can reach out to us if you are unsure of how to proceed with testing.
MONAI Deploy App SDK’s code coverage report is available at CodeCov.
Building the documentation¶
MONAI’s documentation is located at
./run gen_docs # '-h' for help
The above command builds HTML documents in the
dist/docs folder, they are used to automatically generate documents in https://docs.monai.io.
To test HTML docs locally with development server, execute below command:
./run gen_docs_dev # '-h' for help
The above command launches a live server to build docs in runtime.
Before submitting a pull request, it is recommended to:
edit the relevant
For Diagram, we use sphinxcontrib-mermaid.
classDiagramto visualize Operator (as a class) with multiple input/output labels (input attributes as fields, output attributes as methods) and connections between operators (as an edge label).
Please check #124 for the detailed instruction.
check the auto-generated documentation (by browsing the generated documents after executing
build HTML documentation locally (
./run clean_docsto clean temporary and final documents.
Automatic code formatting¶
Signing your work¶
MONAI enforces the Developer Certificate of Origin (DCO) on all pull requests.
All commit messages should contain the
Signed-off-by line with an email address. The GitHub DCO app is deployed on MONAI. The pull request’s status will be
failed if commits do not contain a valid
Git has a
--signoff) command-line option to append this automatically to your commit message:
git commit -s -m 'a new commit'
The commit message will be:
a new commit Signed-off-by: Your Name <firstname.lastname@example.org>
Full text of the DCO:
Developer Certificate of Origin Version 1.1 Copyright (C) 2004, 2006 The Linux Foundation and its contributors. 1 Letterman Drive Suite D4700 San Francisco, CA, 94129 Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed. Developer's Certificate of Origin 1.1 By making a contribution to this project, I certify that: (a) The contribution was created in whole or in part by me and I have the right to submit it under the open source license indicated in the file; or (b) The contribution is based upon previous work that, to the best of my knowledge, is covered under an appropriate open source license and I have the right under that license to submit that work with modifications, whether created in whole or in part by me, under the same open source license (unless I am permitted to submit under a different license), as indicated in the file; or (c) The contribution was provided directly to me by some other person who certified (a), (b) or (c) and I have not modified it. (d) I understand and agree that this project and the contribution are public and that a record of the contribution (including all personal information I submit with it, including my sign-off) is maintained indefinitely and may be redistributed consistent with this project or the open source license(s) involved.
MONAI provides a set of generic utility functions and frequently used routines.
These are located in
Users are encouraged to use these common routines to improve code readability and reduce code maintenance burdens.
For string definition, f-string is recommended to use over
format-print from python 3.6. So please try to use
f-string if you need to define any string object.
Submitting pull requests¶