Skip to content

Latest commit

 

History

History
215 lines (144 loc) · 8.31 KB

CONTRIBUTING.md

File metadata and controls

215 lines (144 loc) · 8.31 KB

Contributing to mplc

Please, feel free to suggest any other relevant item, to ask for edits or even to submit a Pull Request! You can also have a look at these broader contributing guidelines.

Table of content:

  1. Git workflow & branching
  2. Python
    1. Python Virtual Environment
    2. Python Enhancement Proposals (PEP)
    3. Basic module structure & Imports order
    4. Jupyter Notebooks
    5. Sharing & online rendering
  3. Further Resources

1. Git workflow & branching

The branching model of the project is a very simplified of the standard approach:

  • The master branch is protected
  • Contributors create a feature branch from master, push it to the repository and open a draft PR
  • Once automated tests passe, their PRs are reviewed and merged by the repository maintainers

Note: If you are not yet part of the contributor list, please get in touch with us. In the meantime, you can create your own fork of the project and open a PR pointing to this source repository, so we can evaluate your submission. Github documentation.

2. Python

2.i. Python Virtual Environment

In order to keep your installation separated from your general Python environment, which is a general Python good practice, it is recommended to set up a Python virtual environment. In a new terminal window, please use one of the following method:

# Method 1: install the virtualenv package
pip3 install --user virtualenv

# Create a new virtual environment
virtualenv -p python3 NAME_OF_YOUR_VENV
# or even
virtualenv -p $(which python3) NAME_OF_YOUR_VENV

# Method 2: install the python3-venv package
sudo apt install python3-venv # (Ubuntu)

# Create a new virtual environment
python3 -m venv NAME_OF_YOUR_VENV

# Method 1 & 2: activate your new virtual env
source NAME_OF_YOUR_VENV/bin/activate

# Method 1 & 2: stop your virtual environment
deactivate

Some of you might prefer to use Anaconda, if so, you will be able to manage your virtual environment like this:

# Create a new virtual environment
conda create --name NAME_OF_YOUR_VENV

# Activate your new virtual environment
conda activate NAME_OF_YOUR_VENV

# Stop your virtual environment
deactivate

Once inside your new virtual environment, you can install the project dependencies with the commands:

  • pip setup: pip3 install -r dev-requirements.txt
  • anaconda setup: conda install --file dev-requirements.txt

What is installed inside a virtual environment is separated from your general Python setup.

If you want to go further, please refer to the official documentation.

If you are looking for more Python Virtual Environment resources, you might be interested in this post from Real Python.

Please note that you can then select your new virtual environment as any other Python interpreter in your favorite IDE and be able to use the new installed packages as if it were installed on your general Python setup.

2.ii. Python Enhancement Proposals (PEP)

Black formatter

This tool might seem a little bit radical, but it is based on PEPs and offers several possibilities of customization. It will help you learn and improve your code.

You don't have to take all the suggested modifications (with the help of git diff) but it is a good reference based on PEP rules that will ensure validity, maintainability and readability of the code.

Link: Black package repository.

Installation
pip3 install black

# with anaconda
conda install -c conda-forge black
Usage
# Inspect a file
black FILE.py

# Inspect files in the current folder
black .

Flake8 linter

Flake8 is a famous Python linting package that might be of help within your development environment. It will help ensure the correct format of your code.

Note: flake8 is part of the automated tests of the repository executed by Travis. Incorrect code formatting will automatically lead to failed tests.

2.iii. Basic module structure & Imports order

# -*- coding : utf-8

"""
Documentation of module
"""

# 1. imports from standard library (ex. sys)

# 2. imports from third party library (ex. arrow)

# 3. imports from project modules (project internal modules)

# 4. global variables

# 5. definition of exception classes

# 6. definition of other classes

# 7. definition of contributivity_methods

# 8. Python main function
def main():
    """
    Documentation of the method
    """
    (...)

if __name__ == '__main__':
    main()

2.iv. Jupyter Notebooks

"The future is now, old man!"

Jupyter Notebooks are awesome! It allows you run Python code (but not only!) in your favorite web browser and handles for you all the backend management so you can focus on writing your code in cells, or your notes directly in markdown! There are plenty of fresh contents about ways to adopt, adapt or trick notebooks. If not yet familiar with it, you really should have a look: https://jupyter.org/.

Plus, Jupyter Notebooks come with a serious set of crazy cool and neatly documented widgets, help yourself.

Note: Jupyter lab is like the future of Notebook, be sure to have a look, you might like it!

2.v. Sharing & online rendering

Notebooks now have really efficient ways to share your code and display your outputs, among them, you will find:

  • Binder that lets you turn a Git repository into a collection of interactive notebooks!
  • Voila is a newcomer that will allow to build dashboards for your presentations!
  • Colab offers online, cloud-hosted notebooks and its free plan enables usage of GPUs

2.vi. Run the tests

You will first need to install the dev dependencies with pip3 install -r dev-requirements.txt and then run:

# Run unit tests with default configuration
make tests-units
# To run tests with custom the parallelism level, the test runner can be invoked itself
tox -e unit --parallel n
# Run a test suite with full log output, with the option -- --debug:
tox -e unit -- --debug
# Run with python
python3 -m pytest -vv tests/unit_tests.py
# Fall in debugger breakpoint in case of error
pytest -vv tests/unit_tests.py --pdb
# Run tests and produce a coverage measure. This will output a .coverage file
pytest -vv --cov=mplc tests/unit_tests.py

2.vii. Release a new build

To release a new version on PyPI, go at the root of the repository, and trigger the build with pip. You will need all the dev-requirements installed.

$ pip install -r dev-requirements.txt

Make sure that you have the right access to PyPI, and enable the 2FA for safety purpose.

$ python3 setup.py sdist bdist_wheel
$ twine upload dist/*

3. Further Resources