Skip to content

Latest commit

 

History

History
314 lines (245 loc) · 16.8 KB

CONTRIBUTING.md

File metadata and controls

314 lines (245 loc) · 16.8 KB
Raw

Contributing to OpenVINO Notebooks

Thank you for being interested in contributing to the OpenVINO Notebooks repository! This guide explains the design decisions, requirements, and coding guidelines for the OpenVINO Notebooks repository. Please read the Design Decisions and Validation sections before jumping to the Getting Started section.

The goal of this document is to make it as easy as possible to contribute to the OpenVINO Notebooks repository, while maintaining the quality and consistency of the notebooks in the repository.

If you have a question, about the notebooks or about contributing to the repository, please create a discussion!

Design Decisions

The goals of the OpenVINO Notebooks are:

  • to make it easy to get started with OpenVINO.
  • to teach how to use OpenVINO tools to do inference, convert and quantize models.
  • to make it easy to use models from OpenVINO's Open Model Zoo and other public models.

To do this, there are a few requirements that all notebooks need to pass.

General design considerations

  1. The notebooks work on Windows, macOS and Linux (see supported operating systems) with Python 3.7, 3.8, 3.9 and 3.10.
  2. As a rule, the notebooks do not require installation of additional software that is not installable by pip. We do not assume that users have installed XCode Dev Tools, Visual C++ redistributable, cmake, etc. Please discuss if your notebook does need C++ - there are exceptions to this rule.
  3. The notebooks should work on all computers, and in container images. We cannot assume that a user will have an iGPU or a webcam, so using these should be optional. For example, In the case of webcam inference, provide the option to use a video.
  4. The notebooks should work in Jupyter Lab and Jupyter Notebook. If a dependency does not work in either of these, the notebooks should still be usable: use graceful degradation. For example, if a visualization library only works in Jupyter Lab, but offers substantial advantages, make sure that a user who runs Jupyter Notebook still sees the output, even if it is not interactive/3D/annotated/etc.
  5. With the exception of notebooks that demonstrate training of neural networks, all notebooks should by default run in less than five minutes with "Run All Cells" (excluding time required to download files). If this means using a smaller model or smaller dataset that gives less than optimal results, or having a less amazing visualization, provide the better option that takes longer as an option.
  6. Not everyone who uses the notebooks will have a fast computer and/or fast internet. It is not always possible to use a smaller model or a smaller dataset, but if it is, please do that, and provide an option for the larger model or dataset.
  7. The target audience for the notebooks includes both experienced and new developers. The goal is not just to show the output of a model, but to teach how OpenVINO works, by interacting with it. Not all notebooks need to be full-fledged tutorials, but it is always good to explain steps and add comments.
  8. Respect for human rights is rooted in our values at Intel. We will not accept contributions that perform facial recognition or analyze demographics like age and gender.

Implementation choices

  1. The notebooks use one shared requirements.txt. If "the notebooks don't work" it is often caused by a dependency of a dependency having an issue. We are therefore reluctant to add new dependencies and will only add them if they add real value. Do not let this discourage you if you do want to include a certain package! If it is necessary, or can be useful for other notebooks too, we are open to adding it.
  2. The notebooks are located in the "notebooks" subdirectory. There is a subdirectory for every notebook, with generally the same base name as the notebook. For example, the 001-hello-world.ipynb notebook can be found in the 001-hello-world directory.
    • See the Notebook naming section below, for the numbering of the notebooks.
    • Add a README to the notebook subdirectory. Add a screenshot that gives an indication of what the notebook does if applicable.
    • Add any supporting files to this subdirectory too. Supporting files should be small (generally less than 5MB). Larger images, datasets and model files should be downloaded from within the notebook.
  3. All related files, with the exception of Open Model Zoo models, should be saved to the notebook subdirectory, even if that means that there is a small amount of duplication. For Open Model Zoo models, see the directory structure in the 104 Model Tools notebook.
  4. The notebooks should provide an easy way to clean up the downloaded data, for example with a commented-out cell at the end of the notebook.

Coding Guidelines

  1. See https://www.python.org/dev/peps/pep-0020/
  2. Format notebook code with Black, with a line width of 100. See Tools.
  3. Use f-strings for string formatting: https://www.python.org/dev/peps/pep-0498/
  4. Use keyword/named arguments when calling a function with more than one parameter: function(a=1, b=2) instead of function(1, 2)
  5. Use from pathlib import Path for path manipulation instead of os.path
  6. Add type hints to functions: https://www.python.org/dev/peps/pep-0484/
  7. Add ReST style docstrings (see 403 for an example). It is not necessary to specify the parameter type in the docstring, since type hints are already added to the function definition.
  8. Do not use global variables in functions: a function should not depend on values that are defined outside it.
  9. Use ALL_CAPS for constants.
  10. Prefer consistency. Example: if other notebooks use import numpy as np do not use import numpy in yours.

Other things to keep in mind

  1. Always provide links to sources. If your notebook implements a model, link to the research paper and the source GitHub (if available).
  2. Use only data and models with permissive licenses that allow for commercial use, and make sure to adhere to the terms of the license.
  3. If you include code from external sources in your notebook, or in files supporting your notebook, add the name, URL and license of the third party code to the licensing/third-party-programs.txt file

Notebook naming

Names should be descriptive but not too long. We use the following numbering scheme:

  • 000- hello world like notebooks: very small tutorials that help to quickly show how OpenVINO works.
  • 100- OpenVINO tool tutorials: explain how to optimize and quantize notebooks.
  • 200- OpenVINO model demos: demonstrate inference on a particular model.
  • 300- Training notebooks: notebooks that include code to train neural networks.
  • 400- Live demo notebooks: demonstrate inference on a live webcam.

Please use the first available number in the branch, trying to fill the holes e.g. choose 206, when there are 205 and 207 and 206 is missing.

READMEs

Every notebook must have a README file that briefly describes the content of the notebook. A simple structure for the README file is described below:

# Title of Tutorial
[brief intro, basic information about what will be described]

## Notebook Contents
[more details, possibly information about research papers, the model(s) used and/or data]
Additional subsections, e.g license information.


## Installation Instructions
[link to installation guide, other important information for install process]

Every notebook is also added to the notebooks overview table in the main README and the README in the notebooks directory Notebooks that work in Binder have a Launch Binder badge in the README files.

File Structure

To maintain consistency between notebooks, please follow the directory structure outlined below.

notebooks/
└── data/
   └── video
   └── image
   └── audio
   └── text
   └── json
   └── font
   └── pts
└──<three-digit-number>-<title>/
   ├── README.md
   ├── <three-digit-number>-<title>.ipynb
   ├── utils/
   ├── model/
   └── data/

In case of output provided by Notebook please create folder output on the same level as readme file.

Recommendations for File Structure

  • Model

We recommend to load the model using url otherwise we can accept the model placed in the model folder which will be evaluated further for storage constraints.

  • Data

We recommend to use embedded URL for image/video data since GitHub limits the size of files allowed in repositories. Follow the below instructions to create embedded URL in GitHub:

  • Go to any issue on GitHub.

  • In the comment section, you can attach files. Just drag/drop, select or paste your image.

  • Copy the code/link displayed in the text area Otherwise we can accept the data placed in the common data/ folder which will be evaluated further for storage constraints.

  • License

If you download or include a model, it must be licensed under an open source license like Apache 2.0 which allows for redistribution, modification and commercial use.

Any datasets, images or videos used for fine-tuning, quantization or inference inside a notebook must be licensed under Creative Commons 4.0 (CC 4.0) with permission for commercial use. If commercial use is not allowed, but the data is under CC 4.0, special approval will be required. Please let us know in your pull request if your data has any restrictions on use.

Notebook utils

The notebook_utils.py file in the notebooks/utils directory contains utility functions and classes that can be reused across notebooks. It contains a download_file() function that optionally shows a progress bar, and a standard way to convert segmentation maps to images and display them. The Python file is generated from notebook_utils.ipynb notebook in the same directory. If you want to add a function or class to notebook_utils.py, please add it to the notebook, and generate the Python file with jupyter nbconvert notebook_utils.ipynb --TagRemovePreprocessor.remove_cell_tags=hide --to script Add a "hide" tag to any demo cells (from the right side gear sidebar) to prevent these cells from being added to the script.

Requirements

If you need to add a requirement, add it to requirements.txt and .docker/Pipfile. Use Python 3.8 to install pipenv, and run pipenv lock in the .docker directory to create Pipfile.lock. Add all three files to the repository.

Validation

Automated tests

We use Github Actions to automatically validate that all notebooks work. The following tests run automatically on a new notebook PR:

  • nbval: tests that the notebooks execute without problems on all supported platforms.

  • codecheck:

    • Uses flake8 to check for unnecessary imports and variables and some style issues
    • Verifies that the notebook is included in the main README and the README in the notebooks directory.
    • Runs the check_install script to test for installation issues

  • docker_nbval: tests that the docker image builds, and that the notebooks execute without errors in the Docker image. To manually run this test, build the Docker image with docker build -t openvino_notebooks . and run the tests with docker run -it --entrypoint /tmp/scripts/test openvino_notebooks. It is recommended to build the image on a clean repo because the full notebooks folder will be copied to the image.

  • CodeQL

    • In the rest of this guide, the automated tests in Github Actions will be referred to as CI (for Continuous Integration).

If your notebook takes longer than a few minutes to execute, it may be possible to patch it in the CI, to make it execute faster. As an example, if your notebook trains for 20 epochs, you can set it to train for 1 epoch in the CI. If you do inference on 100 frames of a video, you can set it to do inference on only 1. See this Wiki page for more information.

Manual test and code quality tools

See Getting started about installing the tools mentioned in this section.

nbval

Tests are run in the CI with nbval, a plugin for py.test.

To run nbval locally, run pytest --nbval . to run the tests for all notebooks, or pytest --nbval notebook.ipynb for just one notebook. nbval fails if the notebook environment is not openvino_env.

nbqa

nbqa allows using a variety of code quality tools on Jupyter Notebooks. For example nbqa flake8 notebook.ipynb will warn about unused imports.

nbdime

nbdime has several useful tools, among which nbdiff-web to show the difference between two notebooks in a web browser. nbdiff can also be used as the standard diff tool for git, with much more useful output than the regular git diff output.

JupyterLab Code Formatter

JupyterLab Code Formatter adds a button to Jupyter Lab to automatically format the code in notebooks with black and isort. Please use either this extension or a different way to automatically format your notebook.

Getting started

  1. Create a fork, a copy of the repository, by clicking on the Fork button on the top right of the OpenVINO Notebooks Github page
  2. Install the recommended packages for a development environment with pip install -r .ci/dev-requirements.txt inside the openvino_env enviroment. This installs all the packages mentioned in the Validation section.
  3. Create a branch in this fork, from the main branch. Name the branch however you like.
  4. Doublecheck the points in the Design Decisions and Validation sections.
  5. Check that your notebook works in the CI
    • Go to the GitHub page of your fork, click on Actions, select nbval on the left. There will be a message This workflow has a workflow_dispatch event trigger. and a Run workflow button. Click on the button and select the branch that you want to test.
  6. Test if the notebook works in Binder and if so, add Launch Binder badges to the README files.

Once your notebook passes in the CI and you have verified that everything looks good, make a Pull Request!

Pull Requests (PRs)

  1. If some time has passed since you made the fork, rebase or merge your fork to the openvino_notebooks main branch first.
  2. Create your PR against the openvino_notebooks main branch.
  3. Please create a description of what the notebook does with your PR. Screenshots are appreciated!
  4. On making or updating a Pull Request, the tests in the CI will run again. Please keep an eye on them. If the tests fail and you think the issue is not related to your PR, please make a comment on your PR.

Help

If you need help at any time, please open a discussion! If you think one of the guidelines is too strict, or should not apply to you, feel free to ask about that too.