Developer Guide

PyRETIS is open source and hosted on gitlab. We are happy to include more developers and we want active users. If you wish to contribute to the PyRETIS project, please read through the code guidelines and the short description on contributing given below.

Guidelines

The guidelines can be summarised as follows:

  • Check that your code follows pep8.
  • Document your code using NumPy style docstrings
  • Use a logger rather than print() in libraries.

PyRETIS follows the Python pep8 style guide (see also pep8.org) and new code should be checked with the pep8 style guide checker and pylint:

pycodestyle source_file.py
pylint source_file.py

or other tools like PyChecker or pyflakes. NumPy’s imports can be a bit tricky understand so you can help pylint by doing

pylint --extension-pkg-whitelist=numpy source_file.py

There is also the

import this

which can be useful to remember.

The PyRETIS project is documented using the NumPy/SciPy documentation standard and contributors are requested to familiarise themselves with this style and use it. Documentation style can be checked with pydocstyle

pydocstyle source_file.py

We also try to avoid print() statements in the libraries and reserve such statements for console output from command line scripts/programs. Output, like debug information, warnings etc. can be handled by using a logger. In a library, we typically just import and set up the logger by doing:

import logging
logger = logging.getLogger(__name__)  # pylint: disable=C0103
logger.addHandler(logging.NullHandler())

We can then use it as follows:

# Report some information
logger.info('Up and running')
logger.debug('Debug info')
logger.warning('This is a warning')
logger.critical('Something critical happened!')
logger.error('An error occurred!')

Please note that we do not add any particular handlers here - it is up to the user to define what should happen when a logging event occur.

Contributing to PyRETIS

There is a nice guide on github about contributing to open source projects. In PyRETIS we largely follow this approach and the issue tracker is used for reporting bugs and issues and requesting new features. This section on contributing is based on the description for gitlab.

Before contributing, please read the short guidelines given below for reporting bugs and issues and for requesting new features.

Bugs and issues

If you find a bug in PyRETIS, please create an issue using the following template:

Summary
-------

One sentence summary of the issue: What goes wrong, what did you expect to happen

Steps to reproduce
------------------

Describe how the issue can be reproduced.

Expected behavior
-----------------

Describe what behavior you expected instead of what actually happens.

Relevant logs
-------------

Add logs from the output.

Output of checks
----------------

Be sure that all the tests pass before filing the issue.

Possible fixes
--------------

If you can, link to the line of code that might be responsible for the problem.

If you wish to fix the bug yourself, please follow the approach described for merge requests below.

New features

If you are missing some functionality in PyRETIS you can create a new issue in the issue tracker and label it as a feature proposal. If you do not have rights to add the feature proposal label, you can ask one of the core members of the PyRETIS project to add it for you.

You can also implement the changes you want yourself as described below. We cannot promise that we will automatically include your work in PyRETIS but we are happy to have active users and we will consider your contribution. So, when you are finished with your work please make a merge request.

Merge requests

The general approach for making your bug-fix or new feature available in the PyRETIS project is as follows:

  1. Fork [1] PyRETIS into your own personal space.
  2. Create a new branch and work on your feature.
  3. Create tests for your feature. Especially, if you are fixing a bug, create a test that shows where the bug is causing PyRETIS to fail and how your code is fixing this.
  4. Squash all your commits into one and push to your fork.
  5. Submit a merge request to the master branch using the template given below.
  6. Wait for review and the following discussion :-).
Summary
-------

What does this merge request do?

Justification
-------------

Why is this merge request needed?

Description of the new code
---------------------------

A short description of the new code.
Are there points in the code the reviewer needs to double check?

References
----------

Add references to relevant issue numbers.

After submitting the merge request the code will be reviewed [2] by (another) member of the PyRETIS team.

[1]Gitlab documentation on forking: http://doc.gitlab.com/ce/workflow/forking_workflow.html
[2]https://github.com/thoughtbot/guides/tree/master/code-review