Contribuer

Les contributions sont les bienvenues et sont très appréciées ! Chaque petite contribution est utile, et le crédit sera toujours accordé.

Vous pouvez contribuer de différentes manières :

Types de contributions

Signaler les bogues

Signalez les bogues à https://github.com/hydrologie/xhydro/issues.

Si vous signalez un bogue, veuillez inclure :

• Le nom et la version de votre système d’exploitation.

• Tout détail sur votre installation locale qui pourrait être utile pour le dépannage.

• Etapes détaillées pour reproduire le bogue.

Corriger un bogue

Recherchez les bogues dans les problèmes de GitHub. Tout ce qui est étiqueté avec « bug » et « help wanted » est ouvert à quiconque veut l’implémenter.

Implémenter des fonctionnalités

Consultez les questions de GitHub pour trouver des fonctionnalités. Tout ce qui est étiqueté « amélioration » et « aide recherchée » est ouvert à quiconque veut l’implémenter.

Rédiger la documentation

xHydro pourrait toujours utiliser plus de documentation, que ce soit dans le cadre de la documentation officielle de xHydro, dans les docstrings, ou même sur le web dans des billets de blog, des articles, etc.

Soumettre un retour d’information

La meilleure façon d’envoyer un retour d’information est de déposer un problème à l’adresse https://github.com/hydrologie/xhydro/issues.

Si vous proposez une fonctionnalité :

• Expliquez en détail comment cela fonctionnerait.

• Le champ d’application doit être aussi restreint que possible, afin de faciliter la mise en œuvre.

• Remember that this is a volunteer-driven project, and that contributions are welcome. :)

Démarrer !

Note

Si vous n’avez jamais utilisé GitHub et git, veuillez d’abord lire ce guide.

Avertissement

Anaconda Python users: Due to the complexity of some packages, the default dependency solver can take a long time to resolve the environment. Consider running the following commands in order to speed up the process:

conda install -n base conda-libmamba-solver
conda config --set solver libmamba

Pour plus d’informations, veuillez consulter le lien suivant : https://www.anaconda.com/blog/a-faster-conda-for-a-growing-community

Alternativement, vous pouvez utiliser le gestionnaire de paquets mamba, qui est un remplacement direct de conda. Si vous utilisez déjà mamba, remplacez les commandes suivantes par mamba au lieu de conda.

Prêt à contribuer ? Voici comment mettre en place xhydro pour le développement local.

1. Si vous n’êtes pas encore un collaborateur de xhydro, créez un embranchement sur le dépôt xhydro sur GitHub.

2. Clone your fork locally:

   git clone git@github.com:your_name_here/xhydro.git
   

3. Install your local copy into a development environment. You can create a new Anaconda development environment with:

   conda env create -f environment-dev.yml
   conda activate xhydro-dev
   make dev
   

   This installs xhydro in an « editable » state, meaning that changes to the code are immediately seen by the environment. To ensure a consistent coding style, make dev also installs the pre-commit hooks to your local clone.

   Lors de la livraison, pre-commit vérifiera que les contrôles black, blackdoc, isort`, ``flake8, et ruff passent, effectuera des corrections automatiques si possible, et avertira des violations qui nécessitent une intervention. Si votre livraison échoue aux vérifications initiales, corrigez simplement les erreurs, ajoutez à nouveau les fichiers, et effectuez une nouvelle livraison.

   You can also run the hooks manually with:

   pre-commit run -a
   

If you want to skip the pre-commit hooks temporarily, you can pass the –no-verify flag to git commit.

1. Create a branch for local development:

   git checkout -b name-of-your-bugfix-or-feature
   

   Vous pouvez maintenant effectuer vos modifications localement.

2. When you’re done making changes, we strongly suggest running the tests in your environment or with the help of tox:

   make lint
   python -m pytest
   # Or, to run multiple build tests
   python -m tox
   

   Note

   Running pytest or tox will automatically fetch and cache the testing data for the package to your local cache (using the platformdirs library). On Linux, this is located at XDG_CACHE_HOME (usually ~/.cache). On Windows, this is located at %LOCALAPPDATA% (usually C:\Users\username\AppData\Local). On MacOS, this is located at ~/Library/Caches.

   If for some reason you wish to cache this data elsewhere, you can set the XHYDRO_DATA_DIR environment variable to a different location before running the tests. For example, to cache the data in the current working directory, run:

   export XHYDRO_DATA_DIR=$(pwd)/.cache

3. Commit your changes and push your branch to GitHub:

   git add .
   git commit -m "Your detailed description of your changes."
   git push origin name-of-your-bugfix-or-feature
   

   If pre-commit hooks fail, try re-committing your changes (or, if need be, you can skip them with git commit –no-verify).

4. Soumettez une Pull Request via le site GitHub.

5. When pushing your changes to your branch on GitHub, the documentation will automatically be tested to reflect the changes in your Pull Request. This build process can take several minutes at times. If you are actively making changes that affect the documentation and wish to save time, you can compile and test your changes beforehand locally with:

   # To generate the html and open it in your browser
   make docs
   # To only generate the html
   make autodoc
   make -C docs html
   # To simply test that the docs pass build checks
   python -m tox -e docs
   

6. Once your Pull Request has been accepted and merged to the main branch, several automated workflows will be triggered:

   • The bump-version.yml workflow will automatically bump the patch version when pull requests are pushed to the main branch on GitHub. It is not recommended to manually bump the version in your branch when merging (non-release) pull requests (this will cause the version to be bumped twice).

   • ReadTheDocs construira automatiquement la documentation et la publiera sur la branche latest du site de documentation xhydro.

   • Si votre branche n’est pas un embranchement (ie : vous êtes un mainteneur), votre branche sera automatiquement supprimée.

   Vous aurez contribué à vos premiers changements dans xhydro !

Avertissement

If your Pull Request relies on modifications to the testing data of xhydro, you will need to update the testing data repository as well. As a preliminary testing measure, the branch of the testing data can be modified at testing time (from main) by setting the XHYDRO_TESTDATA_BRANCH environment variable to the branch name of the xhydro-testdata repository.

Be sure to consult the ReadMe found at https://github.com/hydrologie/xhydro-testdata as well.

Lignes directrices pour les demandes de tirage (pull request)

Avant de soumettre une demande de tirage, vérifiez qu’elle respecte ces directives :

1. The pull request should include tests and should aim to provide code coverage for all new lines of code. You can use the –cov-report html –cov xhydro flags during the call to pytest to generate an HTML report and analyse the current test coverage.

2. Si la pull request ajoute une fonctionnalité, la documentation doit aussi être mise à jour. Mettez votre nouvelle fonctionnalité dans une fonction avec une docstring, et ajoutez la fonctionnalité à la liste dans README.rst.

3. The pull request should work for Python 3.9, 3.10, 3.11, and 3.12. Check that the tests pass for all supported Python versions.

Conseils

To run a subset of tests:

python -m pytest tests/test_xhydro.py

You can also directly call a specific test class or test function using:

python -m pytest tests/test_xhydro.py::TestClassName::test_function_name

For more information on running tests, see the pytest documentation.

To run specific code style checks:

python -m black --check xhydro tests
python -m isort --check xhydro tests
python -m blackdoc --check xhydro docs
python -m ruff check xhydro tests
python -m flake8 xhydro tests

To get black, isort, blackdoc, ruff, and flake8 (with plugins flake8-alphabetize and flake8-rst-docstrings) simply install them with pip (or conda) into your environment.

Code of Conduct

Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.