Thank you for taking the time to read this guide for the package's contribution. I'm glad to know that you may bring a lot to the IPFML package. This document will show you the good development practices used in the project and how you can easily participate in its evolution!
2.1. Python conventions
2.3. Code documentation
2.2. Test implementation
3.1. Build package
3.2. Pull request
This project uses the naming conventions of the git branches set up by the git-flow interface. To make your contribution as easy as possible to inject into the project, you will need to name your git branch as follows:
git branch feature/YourFeatureBranchName
Using git-flow interface:
git flow feature start YourFeatureBranchName
As you perhaps already saw, package contains multiples modules and submodules. It's really import to be well organized package and let it intuitive to access as possible to features.
For the moment there are no precise conventions on the naming of new modules or sub-modules, it must just in a first step respect the hierarchy already in place and avoid any redundancies.
In order to facilitate the integration of new modules, do not hesitate to let me know the name it could have beforehand.
Note that the yapf package is used during build process of ipfml package to format the whole code following these conventions.
In order to allow quick access to the code, the project follows the documentation conventions (docstring) proposed by Google. Here an example:
'''Divide image into equal size blocks Args: image: PIL Image or Numpy array block: tuple (width, height) representing the size of each dimension of the block pil: block type returned (default True) Returns: list containing all 2D Numpy blocks (in RGB or not) Raises: ValueError: If `image_width` or `image_heigt` are not compatible to produce correct block sizes '''
You can generate documentation and display updates using these following commands:
bash build.sh firefox docs/index.html
Do not forget to generate new documentation output before doing a pull request.
This project use the doctest package which enables to write tests into documentation as shown in example below:
"""Cauchy noise filter to apply on image Args: image: image used as input (2D or 3D image representation) n: used to set importance of noise [1, 999] identical: keep or not identical noise distribution for each canal if RGB Image (default False) distribution_interval: set the distribution interval of normal law distribution (default (0, 1)) k: variable that specifies the amount of noise to be taken into account in the output image (default 0.0002) Returns: 2D Numpy array with Cauchy noise applied Example: >>> from ipfml.filters.noise import cauchy_noise >>> import numpy as np >>> image = np.random.uniform(0, 255, 10000).reshape((100, 100)) >>> noisy_image = cauchy_noise(image, 10) >>> noisy_image.shape (100, 100) """
Moreover, tests written are displayed into generated documentation and let examples of how to use the developed function.
One thing to do before submit your feature is to build the package:
python setup.py build
This command do a lot of thing for you:
Do not forget to build documentation as explained in section 2.3.
Or directly use bash script which runs all you need:
Once you have built the package following previous instructions. You can make a pull request using GitHub. A documentation about pull requests is available.
To enhance the package, do not hesitate to report bug or missing feature. To do that, just submit an issue using at one of this labels:
You can also add your own labels too or add priority label:
Whatever the problem reported, I will thank you for your contribution to this project. So do not hesitate.