Contributing

pryv welcomes all contributions! Whether you want to report a bug, request a new feature, contribute code or documentation, you found the right place.

Reporting a bug or submitting a feature request

If you want to either report a bug or request a feature, you should create a new issue on Github.

For bug reports, include the version of pryv you observer the bug to happen. You can get pryv’s version by running:

pryv version

Contributing code

If you want to contribute with code, the following guide is made for you. You might also want to have a look at the reference.

Version control

pryv is versioned using Git and its code is available on Github on its main repository. To contribute with code to pryv you will need to create a Github account.

Getting the code

The easiest and preferred way to contribute to pryv is to fork its main repository on Github. To do so, browse the project’s repository and click on the Fork button.

Now, clone the forked project to your local machine:

git clone git@github.com:your-username/pryv.git

Tip

Several tools are provided along with the code to ensure quality code. pryv uses tox to automate this tools (e.g. creation of an environment, installing extra dependencies). Install it using:

pip install --upgrade tox

Isolating your environment

In order not to pollute your local setup and to ensure you are using the same environment as the one required by pryv, you should use a virtual environment. virtualenv is the preferred method.

Install it using pip:

pip install --upgrade virtualenv

Go to the root directory of pryv and create a virtualenv (named venv for example) using:

virtualenv venv

Enter (activate) the virtualenv (note that you need to do the following command each time you want to enter the virtualenv):

source venv/bin/activate

You can now develop and issue all required installations without polluting your machine’s Python environment.

When you are finished developing, you can exit the virtualenv using:

deactivate

Creating a branch

Never work directly on master, always branch before making any changes. Grab ID of the issue you target.

If the issue is a feature request, use the following to create a new branch:

git checkout -b feat/123-short-description

If the issue is a bug, use:

git checkout -b fix/123-short-description

123 is to be replaced with the ID of the issue and short-description is a short description of the issue. Its value is up to you, just try to be as specific and concise as the same time (i.e. max 3 words). Use hyphens (-) in place of spaces.

Writing code

When writing code, try to follow the code conventions. Aim for maximum readability (e.g. short functions, thorough naming of functions, classes and variables). Don’t hesitate to add a small line of comment in the code if you think it can help someone else in the future. Document all functions, even private ones. This ensures someone will be able to understand and use your code in a later stage.

Before merging your code in the main repository, your code will be analysed by several tools. The first one that pryv uses is Pylint. It analyses the code for bad code styling. You can run the following command, prior to your commits in order to verify whether your newly added code follows the rule or not:

tox -e lint

Tip

New code won’t be merged unless they pass the linter.

Testing code

Testing the code is of prime importance to ensure modified code does not break another component. pryv uses pytest and unittest for unit testing. A unit test is an atomic test that aims at validating the behavior of a function (or class method) given some input. Unit tests are written in files located in tests/unit. There is one file, prefixed with test_, per target file to be tested, and eventually a directory, also prefixed with test_, per package to be tested.

pytest offers a mark API that enables one to mark tests as belonging to a specific group. pryv uses it to mark class tests as belonging to unit tests (versus integration tests). A minimal test file looks like:

import pytest
import unittest

from pryv.somewhere import something

@pytest.mark.unit
class TestSomething(unittest.TestCase):
    def test_some_behavior(self):
        self.assertSomething(something(), 'some-value')

To run the unit tests suite without reporting, use:

tox -e unit

To run the unit tests suite and generate a HTML report, use:

tox -e unit-report

The generated report will be available under your root directory in htmlcov.

Commiting code

Try to commit your code regularly. Commit files and changes related to each other.

pryv uses a similar commit naming convention than the Angular’s one:

<type>(<scope>): <subject>

- details description
- details description

<footer>

where <type> can be:

  • feat: for new feature
  • fix: for bug fix
  • refactor: for code refactoring
  • style: for code formatting
  • test: when adding tests or updating existing ones
  • chore: for maintenance

<scope> is the scope of the change:

  • for meta scopes:

    • readme
    • doc
    • setup
  • for modules and packages:

    • core
    • api
    • config
    • cli

and <subject> is a small description of the change starting with an imperative (change, add, fix, not changed nor fixing), in lower case, with no punctuation (i.e. no final .).

The body of the message (optional, but recommended for bigger commits) must be a list of detailed changes, using imperative tenses as well, in lower case, without punctuation.

The footer (optional) can be:

Closes #123

if the commit closes an issue. For a commit that closes several issues, use:

Closes #123, #456, #789

Pushing changes

Once you have finished modifying the code (don’t forget to update the documentation 😉), you can push your local changes to Github using:

git push origin feat/my-branch

Opening a pull request

To merge your changes into pryv’s main repository, you will have to open a pull request.

To do so, go to your repository on Github, click on the Pull request button. Make sure all commits and all changes are there, then fill in the pull request’s description and click on the Send pull request button.

Your changes are now sent to pryv’s maintainers for code review. They might accept your changes or request modifications before merging to pryv’s code base.

Contributing documentation

pryv uses reStructuredText and Sphinx for its documentation. It is located in the docs/ directory of the project (and in the source file for packages, modules, classes and functions documentation).

Since contributing documentation is in many manner, and in particular since documentation is code, you should have a look at the contributing code paragraph of this page.

Building the documentation is all automated thanks to tox. Install it using:

pip install --upgrade tox

Then, build the documentation using:

tox -e docs