Skip to content

Latest commit

 

History

History
150 lines (108 loc) · 4.93 KB

DEVELOPMENT.md

File metadata and controls

150 lines (108 loc) · 4.93 KB
Raw

Development

This document explains how to set up a development environment for contributing to CleanVision.

Setting up a virtual environment

While this is not required, we recommend that you do development and testing in a virtual environment. There are a number of tools to do this, including virtualenv, pipenv, and venv. You can compare the tools and choose what is right for you. Here, we'll explain how to get set up with venv, which is built in to Python 3.

python3 -m venv ./ENV  # create a new virtual environment in the directory ENV
source ./ENV/bin/activate  # switch to using the virtual environment

You only need to create the virtual environment once, but you will need to activate it every time you start a new shell. Once the virtual environment is activated, the pip install commands below will install dependencies into the virtual environment rather than your system Python installation.

Installing dependencies and cleanvision package

Run the following commands in the repository's root directory.

  1. Upgrade pip
python -m pip install --upgrade pip
  1. Install CleanVision as an editable package along with all its extra dependencies
pip install -e ".[all]"
  1. Install development requirements
pip install -r requirements-dev.txt
  1. Inorder to set the path to pytest, it is required to deactivate and activate the environment when pytest is installed.
deactivate
source ./ENV/bin/activate

Testing

Run all the tests:

pytest

Run a specific file or test:

pytest -k <filename or filter expression>

Run with verbose output:

pytest --verbose

Run with code coverage:

pytest --cov=cleanvision --cov-config .coveragerc --cov-report=html

The coverage report will be available in coverage_html_report/index.html, which you can open with your web browser.

Type checking

CleanVision uses mypy typing. Type checking happens automatically during CI but can be run locally.

Check typing in all files:

mypy --strict --install-types --non-interactive --python-version 3.11  src

How to style new code contributions

CleanVision follows the Black code style. This is enforced by CI, so please format your code by invoking black before submitting a pull request. Use the following command to format your code.

python -m black src

Generally aim to follow the PEP-8 coding style. Please do not use wildcard import * in any files, instead you should always import the specific functions that you need from a module. Use the following command to check for style errors.

flake8 --ignore=E203,E501,E722,E401,W503 src tests --count --show-source --statistics

Pre-commit hook

You can also use pre-commit framework to easily set up code style checks that run automatically whenever you make a commit. You can install the git hook scripts with:

pre-commit install

How to build cleanvision docs locally?

  1. Install the required packages to build the docs:
pip install -r docs/requirements.txt

  1. Install pandoc

  2. Build the docs using sphinx-build

sphinx-build docs/source cleanvision-docs

Note for faster build: Executing the Jupyter Notebooks (i.e., the .ipynb files) that make up some portion of the docs, such as the tutorials, takes a long time. If you want to skip rendering these, add `nbsphinx_execute = 'never' to sphinx configuration

  1. To view the docs open the file cleanvision-docs/index.html file in a browser.

EditorConfig

This repo uses EditorConfig to keep code style consistent across editors and IDEs. You can install a plugin for your editor, and then your editor will automatically ensure that indentation and line endings match the project style.

Merging PRs to the codebase

The docs for this repo are hosted by readthedocs.io and can be found here.

Publishing Release

  • Ensure all Checks are successful for your release related PR after getting approvals from other code maintainers.
  • Merge all release related PRs.
  • Go to the Releases in the Github repo and draft a new release.
  • Create a new tag in the format v{version} corresponding to the version being released and click Generate release notes.
  • Before publishing the release, ensure all checks are satisfied as the release on TestPypi and Pypi is automated and an error will result in publishing a new version.
  • Publish release