.. _tba-01-workflow: Workflow ======== Objectifs et principes ---------------------- Ce projet est réalisé en binôme. Les deux étudiants doivent apprendre à travailler sur un même dépôt GitLab, à partager le développement et à intégrer leurs modifications progressivement. L'objectif n'est pas de multiplier les manipulations Git, mais d'acquérir de bonnes pratiques de développement collaboratif. L'organisation retenue est la suivante: - Une branche permanente ``main``, qui contient une version fonctionnelle du projet. - Des branches temporaires pour développer chaque fonctionnalité ou réaliser une correction. - Des Merge Requests (MR) pour intégrer les modifications dans main. - Une relecture croisée : chaque étudiant relit les modifications de l'autre. Organisation des branches ------------------------- Les règles obligatoires sont les suivantes : 1. La branche ``main`` ne doit pas être modifiée directement. 2. Toute nouvelle fonctionnalité ou correction significative doit être développée dans une branche temporaire. 3. Cette branche temporaire doit correspondre à une tâche clairement identifiable. 4. Une branche est supprimée après sa fusion dans ``main``. Convention de nommage ..................... .. csv-table:: :header-rows: 1 :widths: 20, 20, 20 "Préfixe","Utilisation","Exemple" "feature/","Nouvelle fonctionnalité","feature/my-map" "fix/","Correction d'un problème","fix/direction-inconnue" "docs/","Documentation","docs/readme" "test/","Ajout de tests","test/historique" .. note :: Les noms doivent être courts, explicites, en minuscules et sans espaces ni accents. .. _gestion_des_commits: Gestion des commits ------------------- Les règles obligatoires sont les suivantes : - Faire des commits régulièrement, dès qu'une étape cohérente est terminée (une séance) ; - Un commit doit correspondre à une modification identifiable (une séance) ; - Ne pas attendre la fin du projet pour effectuer les premiers commits ; - Ne jamais intégrer de fichiers inutiles (environnements virtuels, caches Python, fichiers temporaires, etc.). Quel fichier permet de filtrer les fichiers à ne pas intégrer dans le dépôt Git ? Convention des messages ....................... Utiliser de préférence les préfixes suivants... .. rubric:: Convention des messages .. csv-table:: :header-rows: 1 :widths: 20, 20, 20 Préfixe, Signification, Exemple feat:, Nouvelle fonctionnalité, feat: add new rooms fix:, Correction, fix: empty command docs:, Documentation, docs: update README test:, Tests, test: add player tests refactor:, Réorganisation du code, refactor: simplify direction choice Les messages doivent être courts, précis et rédigés de préférence en anglais pour adopter une convention courante dans les projets logiciels. .. note:: Bonne pratique : un commit doit représenter une modification suffisamment petite pour être comprise et relue facilement. Merge Requests (MR) ------------------- Une Merge Request permet de proposer l'intégration d'une branche dans ``main``. Les règles obligatoires sont les suivantes : - Chaque fonctionnalité significative doit faire l'objet d'une MR ; - La MR doit : 1. Avoir un titre explicite ; 2. Décrire brièvement les modifications apportées ; 3. Indiquer les éventuels points restant à traiter ; 4. Être relue par l'autre étudiant avant fusion ; 5. Ne pas introduire de régression dans le projet. Relecture croisée ................. Si ``Alice`` est l'auteur de la MR, ``Bob`` est le relecteur, et inversement. Le rôle du relecteur n'est pas simplement de cliquer sur ``Approve``. Il doit notamment vérifier : - La lisibilité du code ; - Le respect des conventions Python ; - La cohérence avec l'architecture du projet ; - Le fonctionnement des modifications ; - La présence de tests pertinents. L'auteur de la MR prend en compte les remarques et effectue les corrections nécessaires. .. important:: L'auteur ne fusionne pas sa MR sans avoir obtenu l'accord de son binôme. Workflow de développement ------------------------- Voici le cycle de travail à reproduire pour chaque fonctionnalité. Étape 1 : Récupérer la dernière version ....................................... Au début du travail : .. code-block:: bash $ git switch main $ git pull origin main Étape 2 : Créer une branche ........................... Par exemple, pour développer l'importation CSV : .. code-block:: bash $ git switch -c feature/import-csv Étape 3 : Développer et committer ................................. Créer/modifier le fichier ``csv_loader.py``. Puis : .. code-block:: bash $ git status $ git add csv_loader.py $ git commit -m "feat: add CSV import" On peut faire plusieurs commits pendant le développement, tant que les règles de :ref:`gestion_des_commits` sont respectées. Étape 4 : Envoyer la branche sur GitLab ....................................... .. code-block:: bash $ git push origin feature/import-csv Étape 5 : Créer une Merge Request ................................. Dans GitLab : - Ouvrir le projet ; - Aller dans ``Merge Requests`` ; - Cliquer sur ``New merge request`` ; - Choisir ``feature/import-csv`` comme branche source ; - Choisir ``main`` comme branche cible ; - Compléter la description. Étape 6 : Faire relire et fusionner ................................... Le binôme relit la MR, demande éventuellement des corrections et donne son accord. La MR est ensuite fusionnée dans main. Étape 7 : Mettre à jour son dépôt local ....................................... Après la fusion, le relecteur met à jour sa branche ``main`` locale : .. code-block:: bash $ git switch main $ git pull origin main Chacun supprime ensuite la branche locale : .. code-block:: bash $ git branch -d feature/import-csv Synthèse du workflow .................... .. mermaid:: :caption: Workflow de développement flowchart TD A["main à jour"] --> B["Créer une branche"] B --> C["Développer"] C --> D["Commits réguliers"] D --> E["Push sur GitLab"] E --> F["Créer une Merge Request"] F --> G["Relecture par le binôme"] G --> H{"Modifications nécessaires ?"} H -->|Oui| C H -->|Non| I["Fusion dans main"] I --> J["Mettre à jour main local"] J --> K["Supprimer la branche"] K --> A Gestion des conflits -------------------- Un conflit apparaît lorsque deux modifications incompatibles concernent une même partie du code. Il ne faut pas considérer un conflit comme une erreur : c'est une situation normale dans le développement collaboratif. Si ``main`` a évolué pendant le développement d'une fonctionnalité : .. code-block:: bash $ git fetch origin $ git switch feature/import-csv $ git merge origin/main Si des conflits apparaissent : 1. Ouvrir les fichiers concernés ; 2. Identifier les modifications d'Alice et de Bob ; 3. Construire une version cohérente du code ; 4. Supprimer les marqueurs de conflit (``<<<<<<<``, ``=======``, ``>>>>>>>``) ; 5. Tester le programme. Puis : .. code-block:: bash $ git add . $ git commit $ git push La MR est alors mise à jour. .. note:: C'est une bonne pratique que de résoudre ensemble les conflits, même si un seul réalise les manipulations Git. Protection de la branche main dans GitLab ----------------------------------------- L'administrateur du projet configure la protection de main. Dans GitLab : Settings → Repository → Branch rules (ou Protected branches selon la version). .. rubric:: Paramètres de protection de la branche main .. csv-table:: :header-rows: 1 :widths: 40, 40 Paramètre, Valeur Branch name, main Allowed to merge, Developers + Maintainers Allowed to push and merge, No one Force push, Disabled Il est ainsi possible de proposer des modifications par MR, mais pas pousser directement sur main. Équilibre du travail entre les deux étudiants --------------------------------------------- L'objectif est que les deux étudiants participent réellement au développement. Les règles obligatoires sont les suivantes : - Les deux étudiants doivent contribuer au code ; - Les deux étudiants doivent participer aux revues de code ; - Aucun étudiant ne doit réaliser seul l'ensemble du projet ; - Chaque étudiant doit être capable d'expliquer les principales parties du projet. Bonnes pratiques : - Répartir les fonctionnalités selon les compétences et les intérêts ; - Éviter une répartition systématique « Alice code, Bob documente » ; - Faire tourner les rôles d'auteur et de relecteur ; - Travailler ponctuellement ensemble sur une fonctionnalité complexe. Synthèse -------- Voici les cinq règles fondamentales : 1. main est protégée et ne reçoit jamais de push direct ; 2. Chaque fonctionnalité significative est développée dans une branche temporaire ; 3. Les commits sont réguliers et explicites ; 4. Chaque fonctionnalité passe par une MR relue par le binôme ; 5. Les deux étudiants contribuent au code et comprennent le projet.