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é « enhancement » et « help wanted » 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.

• N’oubliez pas qu’il s’agit d’un projet mené par des personnes volontaires et que les contributions sont les bienvenues :)

Démarrer !

Note

If you are new to using GitHub and git, please read this guide first.

Avertissement

Utilisateurs d’Anaconda Python : En raison de la complexité de certains paquets, le solveur de dépendances par défaut peut prendre beaucoup de temps pour résoudre l’environnement. Envisagez d’exécuter les commandes suivantes afin d’accélérer le processus :

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. Tout d’abord, clonez le dépôt xhydro localement.

   • If you are not a xHydro collaborator, first fork the xHydro repo on GitHub, then clone your fork locally.

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

   • If you are a xHydro collaborator, clone the xHydro repo directly.

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

2. Installez votre copie locale dans un environnement de développement. Vous pouvez créer un nouvel environnement de développement Anaconda avec :

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

   If you are on Windows, replace the make dev command with the following:

   python -m pip install -e .[dev]
   pre-commit install
   

   Cela installe xhydro dans un état « editable », ce qui signifie que les modifications apportées au code sont immédiatement vues par l’environnement. Pour garantir un style de codage cohérent, make dev installe également les hooks pre-commit sur votre clone local.

   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.

   Vous pouvez également exécuter les hooks manuellement avec :

   pre-commit run -a
   

   Si vous voulez ignorer temporairement les hooks pre-commit, vous pouvez passer l’argument -no-verify à git commit.

3. Créer une branche pour le développement local :

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

   Vous pouvez maintenant effectuer vos modifications localement.

4. Lorsque vous avez terminé les changements, nous suggérons fortement d’exécuter les tests dans votre environnement ou avec l’aide de tox :

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

   Note

   L’exécution de pytest ou tox récupérera et mettra automatiquement en cache les données de test du package dans votre cache local (en utilisant la librairie platformdirs). Sous Linux, celui-ci se trouve dans XDG_CACHE_HOME (généralement ~/.cache). Sous Windows, il se trouve dans %LOCALAPPDATA% (généralement C:\Users\username\AppData\Local). Sur MacOS, celui-ci se trouve dans ~/Library/Caches.

   Si pour une raison quelconque vous souhaitez mettre ces données en cache ailleurs, vous pouvez définir la variable d’environnement XHYDRO_DATA_DIR à un emplacement différent avant d’exécuter les tests. Par exemple, pour mettre en cache les données dans le répertoire de travail actuel, exécutez :

   export XHYDRO_DATA_DIR=$(pwd)/.cache

5. Commetez vos modifications et envoyez votre branche sur GitHub :

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

   Si les hooks pre-commit échouent, essayez de re-commettre vos changements (ou, si nécessaire, vous pouvez les ignorer avec git commit –no-verify).

6. Soumettez une Pull Request via le site GitHub.

7. Lorsque vous apportez vos modifications à votre branche sur GitHub, la documentation sera automatiquement testée pour refléter les modifications de votre Pull Request. Ce processus de compilation peut parfois prendre plusieurs minutes. Si vous êtes en train de faire des changements qui affectent la documentation et que vous souhaitez gagner du temps, vous pouvez compiler et tester vos changements localement avec :

   # 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
   

8. Si des modifications sont apportées à votre branche sur GitHub, vous pouvez mettre à jour votre branche locale avec :

   git checkout name-of-your-bugfix-or-feature
   git fetch
   git pull origin name-of-your-bugfix-or-feature
   

   Si vous avez des conflits de fusion, vous devrez peut-être remplacer git pull par git merge et résoudre les conflits manuellement. Résoudre les conflits depuis la ligne de commande peut être délicat. Si vous n’êtes pas à l’aise avec cela, vous pouvez ignorer la dernière commande et utiliser à la place une interface graphique comme PyCharm ou Visual Studio Code pour fusionner les modifications distantes et résoudre les conflits.

9. Before merging, your Pull Request will need to be based on the main branch of the xHydro repository. If your branch is not up-to-date with the main branch, you can perform similar steps as above to update your branch:

   git checkout name-of-your-bugfix-or-feature
   git fetch
   git pull origin main
   

   Consultez l’étape précédente pour plus d’informations sur la résolution des conflits.

10. Pour éviter des tests inutiles sur des branches qui ne sont pas prêtes à être révisées, le dépôt xhydro est configuré pour exécuter des tests uniquement lorsqu’une Pull Request a été « approved » par un responsable. De même, les notebooks de la documentation ne seront reconstruits que lorsque la Pull Request sera « approved », ou si la Pull Request leur apportera des modifications explicites. Ainsi, des modifications supplémentaires à la Pull Request peuvent être nécessaires une fois la Pull Request approuvée, afin de garantir la réussite des tests et la création de la documentation.

11. Une fois que votre Pull Request a été acceptée et fusionnée dans la branche main, plusieurs flux de travail automatisés seront déclenchés :

    • Le workflow « bump-version.yml » modifiera automatiquement la version de la librairie lorsque les Pull Requests sont poussées vers la branche main sur GitHub. Il n’est pas recommandé de modifier manuellement la version dans votre branche lors de la fusion de Pull Requests (non publiées). Cela entraînera une modification de la version deux fois.

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

    • If your branch is not a fork (i.e. you are a maintainer), your branch will be automatically deleted.

Vous aurez contribué à vos premiers changements dans xhydro !

Avertissement

Si votre Pull Request repose sur des modifications des données de test de xhydro, vous devrez également mettre à jour le dépôt de données de test. Comme mesure de test préliminaire, la branche des données de test peut être modifiée au moment du test (à partir de main) en définissant la variable d’environnement XHYDRO_TESTDATA_BRANCH au nom de la branche du dépôt xhydro-testdata.

Assurez-vous également de consulter le fichier ReadMe disponible sur https://github.com/hydrologie/xhydro-testdata.

Lignes directrices pour les Pull requests

Avant de soumettre une Pull Request, vérifiez qu’elle respecte ces directives :

1. La pull request doit inclure des tests et doit viser à fournir une couverture de code pour toutes les nouvelles lignes de code. Vous pouvez utiliser les arguments --cov-report html --cov xhydro lors de l’appel à pytest pour générer un rapport HTML et analyser la couverture actuelle des tests.

2. Toutes les fonctions doivent être documentées avec des « docstrings » suivant le format numpydoc.

3. If the pull request adds functionality, either update the documentation or create a new notebook that demonstrates the feature. Library-defining features should also be listed in README.rst.

4. Le ChangeLog doit être mis à jour avec une brève description des modifications apportées dans la Pull Request. S’il s’agit de votre première contribution au projet, veuillez ajouter votre nom et vos informations aux fichiers AUTHORS.rst et .zenodo.json.

5. The pull request should work for all currently supported Python versions. Check the pyproject.toml or tox.ini files for the supported versions. We aim to follow the support and drop schedule of Python versions as recommended by the NumPy NEP calendar: https://numpy.org/neps/nep-0029-deprecation_policy.html

Conseils

Pour exécuter un sous-ensemble de tests :

python -m pytest tests/test_xhydro.py

Vous pouvez également appeler directement une classe de test ou une fonction de test spécifique en utilisant :

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

Pour plus d’informations sur l’exécution des tests, consultez la documentation pytest.

Pour effectuer des contrôles de style de code spécifiques :

python -m black --check src/xhydro tests
python -m isort --check src/xhydro tests
python -m blackdoc --check src/xhydro docs
python -m ruff check src/xhydro tests
python -m flake8 src/xhydro tests
validate-docstrings src/xhydro/**.py

To get black, isort, blackdoc, ruff, flake8 (with the flake8-rst-docstrings plugin), and numpydoc (for validate-docstrings), simply install them with pip (or conda) into your environment.

Traductions

Si vous souhaitez contribuer à la traduction française de la documentation, vous pouvez le faire en exécutant la commande suivante :

make initialize-translations

Cela créera ou mettra à jour les fichiers de traduction française dans le répertoire docs/locales/fr/LC_MESSAGES. Vous pouvez ensuite éditer les fichiers .po dans ce répertoire pour fournir des traductions pour la documentation.

Pour plus de commodité, vous pouvez utiliser le script translator.py situé dans le répertoire CI pour traduire automatiquement la documentation anglaise vers le français, qui utilise Google Translate par défaut. Notez que ce script nécessite que le package deep-translator soit installé dans votre environnement.

pip install deep-translator

Notre objectif est d’automatiser ce processus à terme, mais d’ici là, nous souhaitons maintenir la traduction française à jour avec la documentation anglaise au moins lorsqu’une nouvelle version est publiée.

Code de conduite

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.