Contribuer
Merci d'envisager de contribuer à ce projet. Il y a de nombreux moyens pour contribuer, parmi lesquels l'implémentation de fonctionnalités ou la correction de bugs au travers de merge requests, mais aussi l'amélioration de la documentation, ou encore la création de tickets pour de nouvelles fonctionnalités ou des rapports de bugs.
Si vous voulez contribuer, nous vous demandons de rester bienveillant et respectueux.
Demandes de fonctionnalités et rapports de bugs
Avante de créer un ticket, vuillez chercher dans la liste des tickets existants pour voir si quelque chose de similaire n'existe pas déjà.
Dans le cas d'un rapport de bug, le fait de fournir des instructions détaillées pour reproduire le problème peut vraiment aider à le résoudre rapidement. Merci d'utiliser les modèles de tickets qui sont disponibles lors de leur création.
Documentation
La documentation que vous êtes en train de lire a été construite avec Docusaurus et a ses fichiers source dans ce dépôt, dans le répertoire docs/. Ces fichiers source peuvent contenir du markdown mais aussi du code JSX.
Le documentation est générée et déployée sur Gitlab Pages quand la branche est fusionnée sur master.
Contribution au code
Merge requests et intégration continue
Toutes les contributions de code sont faites au travers de pull/merge requests attachées à des tickets (issues), pour permettre d'avoir des discussions et des revues de code, mais aussi pour laisser la CI valider que tout fonctionne.
Dans la mesure du possible, veuillez envisager de soumettre vos idées et de commit / pousser votre travail tôt pour obtenir des retours, plutôt que travailler longtemps sur quelque chose qui pourrait ne jamais être intégré. Avec Gitlab, une nouvelle branche est créée automatiquement avec la merge request.
Essayez de garder vos merge requests petites, idéalement pas plus d'1 ou 2 jours de travail. Pour que votre code soit intégré les tests doivent passer, mais la fonctionnalité peut très bien ne pas être complète. Dans ce cas vous pouvez cacher la fonctionnalité avec du CSS si besoin jusqu'à ce qu'elle soit prête à être montrée.
Commits conventionnels
Nous suivons les directives Commits Conventionnels pour nos messages de commit. Vous pouvez consulter ces directives et l'historique de commit du projet pour avoir une idée de la convention utilisée dans le projet.
Cette convention est suivie sur la branche master, mais vous pourriez ne pas la suivre sur vos branches jusqu'à ce qu'elles soient fusionnées, étant donné que les messages de commit seront fusionnés en un seul commit pour l'ensemble de votre merge request.
Architecture
Pour obtenir des informations sur l'architecture générale utilisée et sur la manière de modifier des éléments spécifiques, veuillez consulter la page de documentation concernant l'architecture.
Qualité du code
Le code doit garder un bon niveau de qualité. Il doit rester lisible, formaté correctement et testé. Le style doit rester responsive. Il doit aussi être accessible autant que possible pour inclure toutes les personnes.
Pour commencer votre contribution de code, veuillez suivre les instructions pour l'installation de l'environnement local.
Accessibilité
Le projet suit les directives WCAG, et plus particulièrement le référentiel RGAA.
Vous devez vous assurer dans la mesure du possible qu'au moins les règles WCAG de niveau AA sont respectées. Il s'agit de celles reprises dans le RGAA.
Pour certaines d'entre-elles, vous pouvez être alerté par le linter du frontend qui utilise eslint-plugin-jsx-a11y pour analyser le code JSX de React et trouver des problèmes d'accessibilité, mais également l'outil axe qui est utilisé sur le code HTML final généré pendant les tests de bout en bout. Mais pour la plupart des règles, vous devrez les vérifier vous-mêmes, ou avec l'aide d'un autre être humain pour vérifier votre code.
Qualité de code du backend
Test et lint
Pour lancer les tests unitaires et les outils de lint, vous pouvez lancer le fichier de script dans le dossier backend :
chmod +x test_all.sh
./test_all.sh
Ce fichier contient en fait toutes les commandes individuelles qui peuvent être lancées :
flake8 ../backend --config=setup.cfg --max-complexity=10 # pour le lint du code
mypy connect_access config --config=setup.cfg # pour la vérification statique des types
black --check . # pour la vérification du style de formatage du code
pytest # pour les tests unitaires
Qualité de code du frontend
Test et lint
Pour lancer tous les tests unitaires et outils de lint, vous pouvez lancer la commande suivante :
yarn test-all
Ce qui correspond à l'ensemble de ces commandes lancées une par une :
yarn lint # pour le lint
yarn type-check # pour la vérification statique des types
yarn type-check:e2e # pour la vérification statique des types des tests de bout en bout
yarn test # pour les tests unitaires
Vous pouvez aussi lancer la vérification du style de formatage du code avec :
yarn format-check
Tests de bout en bout
Les tests de bout en bout sont actuellement situés dans le répertoire du frontend, et utilisent CodeceptJS.
En utilisant l'environnement de développement
Pour lancer le backend et le frontend dans les tests de bout en bout avec l'environnement de développement, vous devez installer aussi pm2 :
npm install -g pm2
Pour éviter le conflit avec des instances démarrées de serveurs de développement de backend et de frontend, les serveurs du backend et du frontend pour les tests de bout en bout sont démarrés par défaut sur les ports 3501 et 3502.
Les tests peuvent être lancés avec :
cd frontend/
yarn e2e
En utilisant l'environnement de production
Vous pouvez exécuter des tests de bout en bout dans l'environnement de production Docker. Cependant, vous aurez toujours besoin d'avoir Node.js installé sur votre machine.
Pour éviter tout conflit avec un autre serveur de production démarré sur votre machine, le serveur pour les tests de bout en bout sera démarré par défaut sur le port 6001.
Les tests peuvent être lancés avec :
cd frontend/
yarn e2e:prod
L'image Docker de production sera construite et exécutée, et toutes les informations seront affichées dans votre terminal.