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
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 hyphences (-
) in place of spaces.
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