Contribuer¶

Les contributions sont les bienvenues et très appréciées ! Chaque petite contribution compte, et un crédit sera toujours donné.

Vous pouvez contribuer de nombreuses manières :

Types de contributions¶

Signaler des bogues¶

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

Si vous signalez un bogue, veuillez inclure :

Le nom et la version de votre système d’exploitation.
Tous les détails concernant votre configuration locale qui pourraient être utiles pour résoudre le problème.
Les étapes détaillées pour reproduire le bogue.

Corriger des bogues¶

Consultez les problèmes sur GitHub pour rechercher des bogues. Tout ce qui est étiqueté « bug » et « help wanted » est ouvert à toute personne souhaitant le résoudre.

Implémenter des fonctionnalités¶

Consultez les problèmes sur GitHub pour rechercher des fonctionnalités. Tout ce qui est étiqueté « enhancement » et « help wanted » est ouvert à toute personne souhaitant l’implémenter.

Rédiger de la documentation¶

xHydro pourrait toujours bénéficier de plus de documentation, que ce soit en tant que partie des documents officiels de xHydro, dans les docstrings, ou même sur le web dans des articles de blog, des publications, etc.

Soumettre des retours¶

La meilleure façon de soumettre un retour est de déposer un problème sur https://github.com/hydrologie/xhydro/issues.

Si vous proposez une fonctionnalité :

Expliquez en détail comment cela fonctionnerait.
Gardez la portée aussi étroite que possible pour faciliter l’implémentation.
Rappelez-vous que c’est un projet piloté par des bénévoles, et que les contributions sont les bienvenues. :)

Commencez !¶

Note

Si vous êtes nouveau dans l’utilisation de GitHub et git, veuillez lire d’abord ce guide.

Avertissement

Utilisateurs d’Anaconda Python : En raison de la complexité de certains packages, le résolveur de dépendances par défaut peut mettre du temps à résoudre l’environnement. Envisagez d’exécuter les commandes suivantes pour 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 packages mamba, qui est un remplaçant direct de conda. Si vous utilisez déjà mamba, remplacez les commandes suivantes par mamba au lieu de conda.

Prêt à contribuer ? Voici comment configurer xHydro pour le développement local.

Tout d’abord, clonez le dépôt xHydro localement.
- Si vous n’êtes pas un collaborateur xHydro, commencez par créer une fork du dépôt xHydro sur GitHub, puis clonez votre fork localement.
  git clone git@github.com:your_name_here/xhydro.git
- Si vous êtes un collaborateur xHydro, clonez directement le dépôt xHydro.
  git clone git@github.com:hydrologie/xhydro.git
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
Si vous êtes sous Windows, remplacez la commande make dev par ce qui suit :
python -m pip install --group dev python -m pip install --editable . prek install
Cela installe xHydro dans un état « modifiable », ce qui signifie que les changements apportés au code sont immédiatement visibles par l’environnement. Pour garantir un style de codage cohérent, make dev installe également les hooks pre-commit dans votre clone local. Il installe également toutes les librairies nécessaires pour exécuter les hooks Extremes.jl du module extreme_value_analysis.
Créez une branche pour le développement local :
git checkout -b name-of-your-bugfix-or-feature
Vous pouvez maintenant effectuer vos modifications localement.
Une fois vos modifications terminées, nous vous recommandons fortement d’exécuter les tests dans votre environnement ou à l’aide de tox :
make lint python -m pytest # Or, to run the tests on multiple builds of Python python -m tox
Note

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

Si pour une raison quelconque vous souhaitez mettre en cache ces données ailleurs, vous pouvez définir la variable d’environnement XHYDRO_DATA_DIR à un autre emplacement 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
Validez vos modifications et poussez votre branche sur GitHub :
git add . git commit -m "Your detailed description of your changes." git push origin name-of-your-bugfix-or-feature
Lors du commit, prek exécutera les vérifications pre-commit qui assurent que les contrôles de qualité du code passent, effectuent des corrections automatiques si possible, et avertissent des erreurs qui nécessitent une intervention. Si votre commit échoue les vérifications initialement, il suffit de corriger les erreurs, de ré-ajouter les fichiers, et de re-commiter.

Vous pouvez toujours exécuter les hooks manuellement avec :
pre-commit run -a
Si vous souhaitez ignorer temporairement les hooks pre-commit, vous pouvez passer l’option –no-verify à git commit.
Soumettez une Pull Request via le site web GitHub.
Lorsque vous poussez vos modifications sur votre branche GitHub, la documentation sera automatiquement testée pour refléter les changements dans votre Pull Request. Ce processus de construction peut prendre plusieurs minutes. Si vous effectuez activement des modifications qui affectent la documentation et souhaitez gagner du temps, vous pouvez compiler et tester vos modifications au préalable 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
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 des conflits en ligne de commande peut être compliqué. Si vous n’êtes pas à l’aise avec cela, vous pouvez ignorer la dernière commande et utiliser un GUI comme PyCharm ou Visual Studio Code pour fusionner les modifications distantes et résoudre les conflits.
Avant de fusionner, votre Pull Request devra être basée sur la branche main du dépôt xHydro. Si votre branche n’est pas à jour par rapport à la branche main, vous pouvez effectuer des étapes similaires à celles mentionnées ci-dessus pour mettre à jour votre branche :
git checkout name-of-your-bugfix-or-feature git fetch git pull origin main
Voir l’étape précédente pour plus d’informations sur la résolution des conflits.
Pour éviter de tester inutilement des branches qui ne sont pas prêtes pour la révision, le dépôt xHydro est configuré pour exécuter des tests uniquement lorsqu’une Pull Request a été « approuvée » par un mainteneur. De même, les notebooks dans la documentation ne seront reconstruits que lorsque la Pull Request est « approuvée », ou si la Pull Request apporte des modifications explicites. Par conséquent, des modifications supplémentaires de la Pull Request peuvent être nécessaires après l’approbation pour s’assurer que les tests passent et que la documentation puisse être construite.
Une fois que votre Pull Request a été acceptée et fusionnée dans la branche main, plusieurs workflows automatisés seront déclenchés :
- Le workflow bump-version.yml mettra automatiquement à jour la version de la librairie. Il n’est pas recommandé de mettre à jour manuellement la version de votre branche lors de la fusion de pull requests (non-livraison). Cela entraînerait une mise à jour de la version deux fois.
- ReadTheDocs construira automatiquement la documentation et la publiera sur la branche latest du site Web de documentation de xHydro.
- Si votre branche n’est pas un fork (c’est-à-dire si vous êtes un mainteneur), votre branche sera automatiquement supprimée.

Vous aurez contribué à xHydro !

Avertissement

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

N’oubliez pas de consulter le ReadMe trouvé sur https://github.com/hydrologie/xhydro-testdata également.

Directives de Pull Request¶

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

La Pull Request doit inclure des tests et viser à fournir une couverture de code pour toutes les nouvelles lignes de code. Vous pouvez utiliser les options –cov-report html –cov xhydro lors de l’appel à pytest pour générer un rapport HTML et analyser la couverture actuelle des tests.
Toutes les fonctions doivent être documentées avec des docstrings suivant le format numpydoc.
Si la Pull Request ajoute une fonctionnalité, mettez à jour la documentation ou créez un nouveau notebook qui montre la fonctionnalité. Les fonctionnalités définissant la librairie doivent également être listées dans README.rst.
Le ChangeLog doit être mis à jour avec une brève description des modifications apportées dans la Pull Request. Si c’est votre première contribution au projet, ajoutez votre nom et vos informations dans les fichiers AUTHORS.rst et .zenodo.json.
La Pull Request doit fonctionner pour toutes les versions de Python actuellement prises en charge. Vérifiez les fichiers pyproject.toml ou tox.toml pour les versions prises en charge. Nous visons à suivre le calendrier de support et de suppression des versions de Python tel que recommandé par le calendrier NEP de NumPy : 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 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 <https://docs.pytest.org/en/latest/usage.html>`_.

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 en français dans le répertoire docs/locales/fr/LC_MESSAGES. Vous pourrez ensuite éditer les fichiers .po de ce répertoire pour fournir des traductions pour la documentation.

Pour plus de commodité, vous pouvez simplement exécuter la commande suivante :

make translate

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

pip install deep-translator
python CI/translator.p

Nous visons à automatiser ce processus éventuellement, mais en attendant, nous voulons garder la traduction française à jour avec la documentation en anglais au moins lors de chaque nouvelle version.

Code de conduite¶

Veuillez noter que ce projet est publié avec un Code de conduite des contributeurs <https://github.com/hydrologie/xhydro/blob/main/CODE_OF_CONDUCT.md>`_. En participant à ce projet, vous acceptez de respecter ses termes.