Contribuer

Merci de votre intérêt pour contribuer à GeoNature-atlas ! Ce document vous guidera à travers les bonnes pratiques et les conventions de développement du projet.

Table des matières

Prérequis

Avant de commencer à contribuer, assurez-vous d’avoir :

  • Python 3.x installé

  • Node.js et npm installés

  • Git installé et configuré

  • Une bonne compréhension de Flask (backend) et JavaScript (frontend)

  • Installer l’application !

  • Installer les dépendances python de développement : pip install ".[dev] (depuis la racine du répertoire)

  • Installer les dépendances javascript de développement npm install --only=dev

La documentation d’installation détaille l’installation d’un environnement de développement de GeoNature-atlas

Qualité et convention du code

Le projet utilise des outils de formatage et de linting pour maintenir une structure de code cohérente.

Python

Le code Python doit être formaté avec Black. La configuration de Black se trouve dans le fichier pyproject.toml.

  • Suivez les conventions PEP 8, appliquées automatiquement par Black

  • Utilisez des noms de variables explicites en anglais

  • Commentez le code complexe

  • Documentez les fonctions avec des docstrings

Formater le code Python

Pour formater automatiquement votre code Python :

black .

Vérifier le formatage sans modifier les fichiers

black --check .

Configuration Black

La configuration Black utilisée dans le projet (définie dans pyproject.toml) :

  • Longueur de ligne : 100 caractères

Ces deux règles ne sont pas dans black mais sont à respecter :

  • CamelCase pour les noms de classe

  • snake_case pour les noms de fonction et de variable

JavaScript

Le code JavaScript doit respecter les règles définies par ESLint (voir atlas/static/eslint.config.js)

  • Respectez les règles ESLint configurées

  • Utilisez const et let, évitez var

  • Préférez les fonctions fléchées pour les callbacks

  • Commentez le code complexe

Lancer le linter JavaScript

Pour vérifier votre code JavaScript :

npm run lint

Corriger automatiquement les erreurs ESLint

npm run format

Processus de contribution

1. Créer une issue

Avant de commencer à travailler sur une nouvelle fonctionnalité ou un correctif, créez une issue pour en discuter avec les mainteneurs du projet.

2. Créer une branche

Créez une branche dédiée à partir de develop :

git checkout develop
git pull origin develop
git checkout -b feature/ma-nouvelle-fonctionnalite
# ou
git checkout -b fix/correction-bug

  • Ne mergez pas la branche develop dans votre branche de feature, utilisez la commande rebase

  • Ne faites pas de commit de lint, privilegiez un git commit --amend pour ajouter le lint au commit comprenant les modifications du code

  • Squashez vos pull requests lorsqu’elles sont prêtes à être relues

  • Assurez vous que les tests passent et que le codecov ne baisse pas

Conventions de nommage des branches :

  • feature/ pour les nouvelles fonctionnalités

  • fix/ pour les corrections de bugs

  • docs/ pour la documentation

  • refactor/ pour les refactorisations

3. Développer et commiter

Effectuez vos modifications en respectant les conventions de code. Faites des commits atomiques avec des messages clairs et descriptifs. Pensez à référencer l’issue dans votre commit.

Ecrivez des tests sur les fonctionnalités que vous développez.

Types de commit courants :

  • feat: nouvelle fonctionnalité

  • fix: correction de bug

  • docs: documentation

  • style: formatage, points-virgules manquants, etc.

  • refactor: refactorisation du code

  • test: ajout ou modification de tests

  • chore: maintenance, dépendances, configuration

4. Pousser votre branche

git push <mon_remote> feature/ma-nouvelle-fonctionnalite

5. Créer une Pull Request

  1. Allez sur GitHub et créez une Pull Request de votre branche vers develop

  2. Remplissez le template de PR avec :

    • Description des changements

    • Référence à l’issue concernée

    • Screenshots si applicable

  3. Assignez des reviewers si nécessaire

6. Review et merge

  • Les mainteneurs examineront votre PR

  • Répondez aux commentaires et effectuez les modifications demandées

  • Une fois approuvée, votre PR sera mergée dans develop

Tests automatisés

Les tests sont écrits avec la librairie pytest. Avant de lancer les tests, assurez vous d’avoir créé une base de données pour les tests.

create database <geonatureatlas_test> with owner <geonatadmin>
\d <ma_base>
CREATE EXTENSION IF NOT EXISTS postgis;

Exporter la variable suivante :

export ATLAS_SETTINGS=/home/theo/workspace/GeoNature-atlas/atlas/tests/test_config.py

Cela définit le fichier de configuration de l’application avec celui qui est fourni pour les tests. Vous pouvez tout à fait utiliser un autre fichier de configuration.

⚠️⚠️ Chaque run de test va supprimer le contenu de la base et la recréer !

Lancer les tests :

pytest

Documentation

  • Mettez à jour la documentation si vos changements affectent l’utilisation de l’application

  • Les fichiers de documentation se trouvent dans le dossier docs/

  • Vous pouvez ajouter votre documentation aux formats :

  • Vous pouvez vérifier la bonne mise en forme de la documentation avec les commandes suivantes :

cd docs
make livehtml

Questions et support

  • Pour signaler un bug, créez une issue

  • Pour contacter l’équipe : voir le fichier README

Merci de contribuer à GeoNature-atlas ! 🦋🌿