Ce guide est destiné aux développeurs souhaitant participer au projet ToDo & Co. Toutes les contributions à ce projet sont les bienvenues !
Avant de faire une pull request, veuillez lire attentivement ce guide et ses différentes recommendations. Si celles-ci ne sont pas suivies, les nouvelles fonctionnalités ainsi que les pull requests ne pourront être approuvées et fusionnées.
Version en anglais disponible ici
Afin de contribuer au projet, commencez par cloner le dépôt et installez le projet sur votre machine de développement.
Le README détaille les étapes nécessaires à l'installation et au lancement du projet.
Pour ajouter une nouvelle fonctionnalité ou corriger un bug, commencez par créer une issue.
Ajoutez un titre, et, s'il y a besoin de plus de précisions, une description détaillée dans le champ correspondant.
N'oubliez de vous ajouter dans le champ Assignees, et également de renseigner les Labels et le Project.
Par exemple, pour une nouvelle fonctionnalité, ajoutez le label feature, et sélectionnez ToDo dans le champ project (pour ajouter automatiquement l'issue dans le project board, afin de suivre le statut des issues).
Lorsque l'issue est créée, veillez à déplacer celle-ci dans la colonne in progress du project board, afin que les autres développeurs soient informés que la fonctionnalité est en cours de développement.
Le projet utilise sur GIT pour suivre les différents changements apportés au projet, et la gestion des branches est basée sur le Git flow.
Chaque nouvelle fonctionnalité ou correction de bug doit être faite sur une nouvelle branche, créée depuis la branche master.
Le projet suit une convention de nommage simple :
- pour une nouvelle fonctionnalité :
feature/<issue-id>-<issue-title> - pour une correction de bug :
bugfix/<issue-id>-<issue-title>
Lorsque la branche est créée, vous pouvez commencer le travail de développement.
Afin de conserver le code du projet le plus maintenable possible, et sans bugs, le code ajouté doit respecter certains standards.
Le projet suit les recommandations des PSR-1, PSR-4 and PSR-12 pour le formatage du code.
Lorsque vous avez installé le projet sur votre machine, des outils facilitant le respect de ces recommandations ont été ajoutées :
- phpstan, outil d'analyse statique du code, met en évidence les erreurs dans le code, par exemple le typage des attributs, etc.
- Easy Coding Standard, outil en ligne de commande qui analyse le code pour trouver d'éventuelles erreurs, en se basant sur des règles prédéfinies (issues de PHP Code Sniffer et PHP CS Fixer). La configuration est disponible dans le fichier
ecs.php. L'outil se lance depuis un terminal, avecvendor/bin/ecs check src/ouvendor/bin/ecs check src/ --fixpour corriger les erreurs.
Veillez à utiliser ces outils régulièrement pour fixer les code smells, comme des typages manquants, formater le code en respectant les PSR, etc.
Ce projet étant développé avec le Framework Symfony, veillez également à respecter les best practices de celui-ci.
Le projet utilise PHPUnit pour les tests.
Pour garder le projet stable, et avec le minimum de bugs, il est impératif de lancer tous les tests et qu'ils passent, avant de commit et de pousser les changements sur le dépôt.
Le README détaille les différentes étapes pour lancer les tests.
L'ajout de tests couvrant les différents cas de la nouvelle fonctionnalité ou de la correction de bug que vous ajoutez sera bienvenu.
Afin de suivre facilement les changements, ou pour annuler une modification apportée au code, pensez à faire des commits réguliers, en utilisant cette convention (basée sur conventional commit) :
feat: <titre du commit>pour une nouvelle fonctionnalitéfix: <titre du commit>pour une correction de bug
Lorsque la nouvelle fonctionnalité ou la correction de bug est terminée, vous pouvez créer une pull request.
Rendez-vous sur la page des Pull requests, et cliquez sur le bouton New pull request.
Sur la page de création de la pull request, vous pouvez ajouter un titre, ainsi qu'une description.
Dans le champ description, il est nécessaire de mentionner l'issue relative à la pull request. Cela permet de déplacer automatiquement l'issue dans la colonne appropriée dans le project board. La syntaxe à utiliser est : Closes #<issue-id>.
De le même manière que lors de la création d'une issue, veillez à renseigner les champs situés sur la droite de la page, pour ajouter les informations nécessaires, par exemple les Reviewers, les Labels, etc.
Les analyses SonarCloud et CodeClimate sont lancées automatiquement lorsque la pull request est créée.
Veuillez vérifier que la qualité du code est conforme aux standards du projet :
- SonarCloud :
- Quality Gate passed
- 0 bugs
- 0 vulnerabilities
- 0 security hotspots
- 0 code smells
- 0% duplication
- CodeClimate :
- 0 issues detected
Sinon, si ces standards ne sont pas respectés, la pull request ne pourra pas être approuvée et ne sera pas fusionnée. Veuillez apporter les corrections nécessaires, jusqu'à ce que toutes les analyses soient valides.
Lorsque toutes les analyses sont au vert, et que la pull request a été approuvée par les reviewers, la pull request peut-être fusionnée.
Merci d'avoir lu ce guide, nous espérons que vous pourrez contribuer et apporter de nouvelles fonctionnalités à ce projet !