pryv welcomes all contributions! Whether you want to report a bug, request a new feature, contribute code or documentation, you found the right place.
For bug reports, include the version of pryv you observer the bug to happen. You can get pryv’s version by running:
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.
Now, clone the forked project to your local machine:
git clone firstname.lastname@example.org:your-username/pryv.git
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
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
venv for example) using:
Enter (activate) the
virtualenv (note that you need to do the following command each time
you want to enter the
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
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.
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
New code won’t be merged unless they pass the linter.
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
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
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>
<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:
for modules and packages:
<subject> is a small description of the change starting with an imperative (
fixing), in lower case, with no punctuation (i.e. no
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:
if the commit closes an issue. For a commit that closes several issues, use:
Closes #123, #456, #789
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
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.
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