Contribution Guideline

[mingxin-zheng]

Is your feature request related to a problem? Please describe.

MONAI tutorial repo lacks a guideline on how to contribute tutorials to the repository, which imposes burdens on maintainer.

Describe the solution you'd like

Adding a CONTRIBUTING.md to the root path.

A draft of the outline

• Welcome message and introduction

• Contributing process (similar to the process in the MONAI Core repo)

  • Submitting PR in GitHub
  • Signing the commits with git commit -s
  • Adding licensing/copyright information for new .ipynb and .py files
    • Code scripts: at the top
    • Jupyter notebook: first markdown block
  • As used in the MONAI repo, contributors first raise an issue, create a branch in contributor's forked repo (suggested by @yiheng-wang-nv).
  • Update the README.md in the root dir for new tutorials (suggested by @binliunls)
  • Info about how to test the tutorial changes in a user's local environment (suggested by @wyli) .

• Style

  • Requirements (which will go through pre-commit checks/CI tests)
    • Add standard cellblocks "Setup environment" and "Setup imports" for every notebook.
      • "Setup environment" should include the pip commands !pip install to install MONAI and other necessary packages.
      • "Setup imports" should import all the library and end with monai.util.print_config().
    • Text outputs should be limited to avoid a large trunk of text outputs (maybe 50 lines should be the limit?)
    • Each folder should have a README.md (suggested by @KumoLiu).
  • Recommendations (won't be covered by tests, but reviewers will take a look)
    • If a dataset needs to be used with the script, contributor needs to provide links to the dataset and make a note about the dataset's licensing info. For example, some dataset may be used for non-commercial purposes only.
    • Avoid large files (dataset files, notebooks > 5M?)
    • Private information should be removed. For example, user name in the file paths in the notebook outputs and metadata.
    • Hyperlinks
      • avoid linking MONAI tutorial resources in the repo using web link (instead, use relative file paths)
      • avoid linking folders (folder links do not work well in Jupyter notebooks)
      • for graphs, it is recommended to download them and add to the repo in the ./figure folder
  • Encouragements (completely up to the contributors)
    • If both jupyter notebook and script are included, contributors can implement the code using torch or ignite separately (suggested by @KumoLiu )
    • Add multi-GPU implementation in the script (suggested by @KumoLiu )

• Benchmarking

  • To meet the requirement of the MONAI Toolkit, A100 should be the standard device for benchmarking in all notebooks. (Contributors may have difficulties to get the computation resources. In that case, can the NV team do it after the initial PR is merged?)

• CI Test Guide (suggested by @tangy5 )

  • documents of what CI will test and how to pass them

[mingxin-zheng]

Adding @KumoLiu @binliunls @yiheng-wang-nv @tangy5 @Nic-Ma @wyli @dongyang0122 @myron @holgerroth @finalelement for visibility. Any suggestion/comments/questions are welcomed!

[yiheng-wang-nv]

Adding licensing information

So far, not all tutorials in the repo have license information, thus will we supply them first?
In addition, is it similar to model zoo that for a new contributed tutorial, license for both dataset and code should be covered?

[yiheng-wang-nv]

Requirements (which will go through pre-commit checks/CI tests)

Suggest to attach a template

[mingxin-zheng]

Adding licensing information

So far, not all tutorials in the repo have license information, thus will we supply them first? In addition, is it similar to model zoo that for a new contributed tutorial, license for both dataset and code should be covered?

Thanks @yiheng-wang-nv . Yes, we needed licensing info for every existing notebook and script file.

The license for dataset may not need coverage. As Andy suggested before, we can add a sentence in the notebook to make a note. For example:
"In addition, please notice that some datasets used in application tutorials are under a noncommercial license. You may not use these datasets for commercial purposes."

[mingxin-zheng]

Requirements (which will go through pre-commit checks/CI tests)

Suggest to attach a template

Sounds like a direction I can check! Can you give an example? Thanks @yiheng-wang-nv

[yiheng-wang-nv]

Requirements (which will go through pre-commit checks/CI tests)

Suggest to attach a template

Sounds like a direction I can check! Can you give an example? Thanks @yiheng-wang-nv

I think we can provide a file template.ipynb, with required sections like Setup environment you mentioned. When we have new requirements, this file should be updated simultaneously

Furthermore, it seems the requirements are for notebooks. Should we also add requirements for .py files?

[yiheng-wang-nv]

Contributing process (similar to the process in the MONAI Core repo)

suggest to add two steps (used in MONAI core) before submit PR:

1. create a ticket
2. create a new branch in your fork

[tangy5]

Do we allow external works to contribute after approval, and strictly follow guidelines? We definitely don't want to include too much works with free degree. But some great related work might benefit to the MONAI community, as some works are not suitable for MONAI Core. Will Tutorial repo a place that house these types of work/demonstration?

Just like Model-Zoo.

[tangy5]

We need clear notebook check guideline for contributors.
Currently, some CI tests and checks are confusing, contributor doesn't know what to handle...
For example, for tutorial notebook including training/inference with epochs, what CI tests will do and rules.
If no training, how to add to the list to avoid triggering such CI tests.

Similar things apply for python script based tutorial as well. We can have a guideline.

[mingxin-zheng]

@tangy5 The question to me is how we can make guideline helpful, instead of restrictive in the contributor's work. For example, we can provide template with some notes about the CI tests, if that's helpful.

[binliunls]

• Welcome message and introduction
• Contributing process (similar to the process in the MONAI Core repo)
  • Submitting PR in GitHub
  • Signing the commits with git commit -s
  • Adding licensing information for new .ipynb and .py files
    • Code scripts: at the top
    • Jupyter notebook: first markdown block
  • (Updated by @yiheng-wang-nv) As used in the MONAI repo, contributors first raise an issue, create a branch in contributor's forked repo.

I‘d like to suggest we add a step for update the tutorial readme with new tutorials after uploading tutorials.

[mingxin-zheng]

Yes that's a good one too. Thanks @binliunls !

[Nic-Ma]

Hi @tangy5 ,

We are doing open source project, always welcome community contributions following the guideline.

Thanks.

[KumoLiu]

Just three small suggestions:

• We may also need to add README.md for each project folder not only for the README in the root dir.
• If both jupyter notebook and script are included, it is recommended that contributors can implement the code using torch or ignite separately. If possible, it is recommended to add multi-GPU implementation in the script.
• l also think “Check first data shape and visualize” can be a standard cellblock that helps users better visualize what the input looks like.

Thanks!

[wyli]

this looks like a duplicate ticket of #761, #118 cc @finalelement

would be great to include some info about how to test the tutorial changes in a user's local environment.