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 featurefix
: for bug fixrefactor
: for code refactoringstyle
: for code formattingtest
: when adding tests or updating existing oneschore
: 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