e3-core/CONTRIBUTING.md

Contributing

Feedback and pull-requests

For feature requests, bug reports, vulnerability reports, and feedback, please provide them as GitHub issues.

To submit a patch please create a pull request from your topic branch. You should create a separate branch for each single topic (bug fix or new feature). Please follow commit message guideline from git-scm book. Try to break several logical changes or bug fixes in several commits.

We also ask you to sign our Contributor Licence Agreement.

Code conventions

pre-commit checks

Before contributing a change please activate pre-commit checks locally:

$ pip3 install pre-commit
$ pre-commit install

Note that the pre-commit check configuration can be found in .pre-commit-config.yaml. Before any change to that file please run:

$ pre-commit run --all-files

The pre-commit checks will format the code with Black and run flake8.

Flake8, mypy, and Black

All code should follow PEP8, PEP257. The code is automatically formatted with Black at commit time.

All changes should contain type hinting and running mypy should be clean of errors.

You should also document your method's parameters and their return values in reStructuredText format:

"""Doc string for function

:param myparam1: description for param1
:param myparam2: description for param1
:return: description for returned object
"""

The code is automatically formatted with Black.

logger

All logging done by e3 must be done via a logger returned by the function e3.log.getLogger. Very verbose logging can be achieved by adding calls to e3.log.debug(). This will be activated when an application using e3.main.Main is run with: -v -v.

Main

All entry points must instanciate e3.main.Main to parse their options.

Exceptions

Exceptions raised by e3 should derived from e3.error.E3Error.

The e3 namespace

The e3 framework provides a namespace package. It allows creating separated packages living under the e3 namespace.

Such a package must:

• define an e3/__init__.py file containing only:

  __import__('pkg_resources').declare_namespace(__name__)
  

• set to e3 the value of the namespace package argument of the setup() function of its setup.py (see setup.py).

See setuptools namespace-packages doc for more info.

Plugin system

e3 uses a plugin system based on stevedore built on top of setuptools entry points. e3-core is meant to be as small as possible and extented with plugins.

To add a new feature based on plugins, first define a base class with abc (Abstract Base Classes) that will implement the plugin interface. Other packages can then create plugin by deriving the base class (the interface) and referencing the entry point in its setup.py. e3-core can then use the plugin via stevedore. See the plugin system documentation.

Documentation

All public API methods must be documented.

e3-core documentation is available in the e3-core GitHub wiki.

Testing

All features or bug fixes must be tested. Make sure that pre-commit checks are activated before any pull-requests.

Requires: tox If not already installed, install it via:

pip install tox

On Windows, you will need additional tools in your PATH to run the testsuite cleanly. If you have installed Git and are using PowerShell, then you can add them by running:

$ENV:PATH += ";$ENV:ProgramFiles/Git/usr/bin"

On macOS, it might be required to add some GNU tools in your PATH. At least one test does not work with patch 2.0-12u11-Apple. You can install GNU patch by running

brew install gpatch

In order to run the public testsuite of e3-core, do:

tox

Coverage

The code needs to be covered as much as possible. We're aiming for 100% coverage. If something cannot be tested on a platform add no cover instruction in the code. This should be done for all platform specific code or for defensive code that should never be executed. See the file tests/coverage_<platform>.rc for patterns to use in order to exclude some line from the coverage report.

Supported Python version

To simplify our testing and reduce the technical debt, we are only supporting the two last versions of Python.