Contribute#
Requirements#
make sure your local
main
branch is up-to date (git switch main && git pull
)install the package in developer mode (see Developers)
install the git hooks (
pre-commit install
)
Development guidelines#
The Git workflow used by this project is the Feature branch workflow
The Python Code style follows PEP8
The docstring style follows numpydoc
Static code analysis is performed with ruff
Unit-testing is performed using pytest
don’t re-invent the wheel, always check if a dependency has what you need before implementing it yourself
make clear atomic commits,
make atomic commits <https://www.aleksandrhovhannisyan.com/blog/atomic-git-commits/> with a clear descriptive message (best practices)
always test your local branch before pushing
pre-commit#
The project comes with a pre-commit configuration which will run some checks each time you attempt to commit.
Some checks will be applied automatically by the associated tool, others with be applied but not staged yet so you can review them before trying to commit again.
Make sure you have installed the git hooks before starting to commit
(pre-commit install
).
Documentation#
The automatic deployment of the documentation happens only on the protected branch (main
).
While working on your contribution you can build your development version locally,
make -C docs clean
if you want to reset from previous buildsmake -C docs html
open
docs/build/html/index.html
with your favorite browser
Please, make sure that the documentation builds without warnings or errors, as the documentation build is set to fail otherwise (in particular, warnings are treated as errors, also by the project’s Sphinx configuration).
Docstrings#
Each API member has to be documented with a docstring.
A simple template for a function is the following,
A one-line summary that does not use variable names or the function name.
A few sentences giving an extended description.
Parameters
----------
x : `~show.only.the_class`
Description of parameter `x`.
y : `int`
Description of parameter `y`.
Returns
-------
result : `show.the.full.class.path`
Description of ``result``.
Please, see the numpydoc style guide for more details.
Changelog#
This project is supported by a changelog to let users know what has been fixed or improved.
Whenever you add a new contribution, you should always open first a new issue to track it, then a Pull Request (PR) that closes that issue.
Every PR needs to add at least one news fragment, a small .rst file under docs/source/changes
containing a description of what was changed in a way that is usefull for the user.
The name of the file has to follow the template PULL_REQUEST_ID.CONTRIBUTION_TYPE.rst
,
where CONTRIBUTION_TYPE
has to be one of the following:
removed
deprecated
added
changed
fixed
For example: a bug fix was found and an issue was opened.
A PR with ID #5 was opened to fix the bug and it introduced the file 5.fixed.rst
which reads,
Fixed a terrible bug which caused this function to output this nonsense result.