Contribute¶

Submit changes¶

Before anything, please keep in mind the following. If one or more of those conditions are not filled. Your Pull Request to PyFunceble may not be merged.

The master branch is used only for releasing a new or stable version of the code. That’s why we require that all contributions/modifications must be done under the dev or a new branch.

In order to gain some time and also understand what you are working on, your pull requests submission as long as your commit descriptions should be clear and complete as much as possible. We do an exception to commit with minor changed but big changes should have a complete description.

Please ensure to use the following method when committing a big change.

Coding conventions¶

Format¶

We should format our code with Black, The uncompromising Python code formatter.
We should write docstrings for every public method, function and classes. It does not have to be elaborate. Just explain what it simply does!

$ black PyFunceble && black tests

Note

You can avoid this secion if you use the production-pyfunceble CLI which already handles as musch as possible.

Linting¶

Our code should pass a pylint check without any issue (exit 0).

$ pylint PyFunceble && pylint tests

Coverage¶

Our code should have at least 60% of coverage.

Note

Coverage unrelevant code/files can be muted.

$ coverage run setup.py test && coverage report -m

Distribution¶

Our code should be shipped (after each commit) with a new version and a new version.yaml file. That file should ALWAYS be generated with the following.

Note

An exception is granted for detached branch (not dev nor master) and no code changes.

$ # Prepare our files, :code:`version.yaml` and code for production/dev usage.
$ PyFunceble --production

Commit¶

All your commits should be - when possible - be signed with PGP. (More information can be found on GitHub documentation) Please note the usage of -S into the commit command which means that we sign the commit.

The commit message may be formatted like follow:

Note

An exception is granted for no code changes.

::

Short explanation (max 79 char).

Paragraphs with some details/context (if needed).

Git Hook¶

If one may want to automate the process.

Here is a git hook (as proposition) to be set into .git/hooks/pre-commit.

#!/usr/bin/env bash

# We print what's going on.
set -x
# We stop on error.
set -e

# We get top level path.
rootDirectory="$(git rev-parse --show-toplevel)"
# We construct our list of directories.
ourDirectories="${rootDirectory}/PyFunceble ${rootDirectory}/tests"

if [[ ! -z "$(git status --porcelain | awk '{ if ($NF > 0 && substr($1,1,1) != "?" && $2 ~ '/\.py/' ) print $2}')" ]]
then
        hash find
        hash isort
        hash black
        hash pylint
        hash coverage

        for directory in $(echo ${ourDirectories})
        do
                # We sort the imports.
                find "${directory}" -name "*.py" -exec isort {} \;
                # We format the code.
                black "${directory}"
                # We lint the code.
                pylint "${directory}"
        done

        cd "${rootDirectory}"
        coverage run setup.py test
fi

set +e
set +x
exit 0