Procédures de travail

Ce chapitre décrit les procédures de travail à appliquer lorsque l’on veut faire des modifications dans le projet principal (dev / sainet).

---

Préambule

1. Chacun est responsable de savoir s’il faut créer une nouvelle branche ou continuer dans une branche existante. En cas de doute, demandez à un admin !
2. Les branches “junk” avec plein de modifications dans tous les sens n’ayant aucun rapport entre elles seront systématiquement refusées lors du code review (= travail refusé).
3. Le nommage des branches est important (se référer au tableau). Les branches mal nommées seront systématiquement supprimées (= travail perdu).
4. Si vous oubliez de soumettre une Merge Request (en créant la branche ou une fois vos modifications terminées), vos modifications ne seront jamais (ré)intégrées au master (= travail inutilisé et non publié).
5. Si vous oubliez de faire le push dans votre branche, vos modifications ne sont pas disponibles sur GitLab (= travail non publié). C’est comme si vous n’aviez pas committé avec Subversion.
6. Les Merge Request sont un outil indispensable au suivi et à la compréhension du code. Lorsque des remarques/questions sont faites, l’auteur du code en question est tenu de répondre/faire les modifications, sans quoi la Merge Request ne sera pas intégrée au master (= travail refusé).
7. La branche de référence pour créer une nouvelle branche est toujours la branche master (sauf cas exceptionnel). Si cela part d’une autre branche, cela provoquera des merge involontaires de code qui seront systématiquement refusés (= travail refusé/perdu).
8. En cas de conflits lors l’intégration dans master (indiqué dans la Merge Request), les participants de la branche sont responsables de les corriger, sans quoi la Merge Request ne pourra pas être validée (= travail refusé/perdu).

---

Checklist

ID	Opération	commande
1	Vérifier la branche courante (en local)	git status
2	Récupérer les dernières modifications (depuis GitLab)	git pull
3	Créer une nouvelle branche (en local)	git checkout -b <branch>
4	Faire les modifications (en local)	git add / git commit
5	Publier sa branche (sur GitLab)	git push
6	Soumettre une Merge Request (sur GitLab)	N/A
7	Suivre la Merge Request (sur GitLab)	N/A

---

Vérifier la branche courante

Cette étape est nécessaire avant toute opération afin d’éviter de devoir faire des “corrections” de branche par la suite.

Il est important de systématiquement se poser la question de créer une nouvelle branche (même si c’est pour un seul commit) et ce, toujours à partir de la branche master (qui est la branche de référence).

Commandes

Utiliser la commande:

git status

Ce qui produit le résultat suivant:

On branch master
Your branch is up to date with 'origin/master'.

Attention: Ce n’est pas car git vous dit que la branche est à jour qu’elle l’est vraiment ! Git compare par rapport à ce que vous avez téléchargé localement, mais il y a peut-être eu d’autres modifications en ligne entre deux.

Si la branche courante n’est pas master, pour changer de branche:

git checkout master

---

Récupérer les modifications distantes

A ce stade, la branche courante devrait être master (voir étape précédente).

Pour récupérer les modifications en ligne:

git pull

Cela va récupérer les dernières modifications du repo et mettre à jour votre branche master locale.

---

Créer une nouvelle branche

Pour créer une nouvelle branche, utiliser la commande suivante:

git checkout -b <branch>

La nomenclature de la branche est importante !!! Cela a de multiples impacts (éviter les conflits, facilité de recherche, …). Il est donc impératif de respecter cette nomenclature sous peine de voir sa branche supprimée ! Les différents préfixes sont expliqués ici.

Par exemple, pour la correction du ticket 28711 pour val, la branche à créer sera:

git checkout -b fix/val/ma-28711

Désormais, vous êtes sur une nouvelle branche locale (pour l’instant elle n’est que sur votre machine). Un git status affichera:

On branch fix/val/ma-28711
nothing to commit, working tree clean

A ce stade, vous pouvez commencer vos modifications.

---

Nomenclature des branches

Préfixe	Type de branche
fix/<site>/ma-<ticket>	Corrections pour le site <site> selon le ticket mantis <ticket>
fix/<site>/<nom>	Corrections pour le site <site>
fix/sainet/<nom>	Corrections générales SAINet
feature/<site>/<nom>	Développement de nouvelles fonctionnalités pour le site <site>
feature/sainet/<nom>	Développement de nouvelles fonctionnalités générales SAINet
dev/<site>/<nom>	Branches de développement pour nouveau client
dev/<nom>	Branches de développement pour tests divers
stable/<nom>	Branches stables pour backport (branches protégées)
demo/<nom>	Branches pour démo

---

Effectuer des modifications

Votre branche va contenir un ou plusieurs commits. C’est à ce moment qu’il est important de prendre en compte le découpage du travail. A savoir, les modifications dans une branche doivent toutes être relatives au même sujet (car une branche, même avec plusieurs commits, correspond à une merge request) et sera relue de manière globale (avec toutes les modifications en bloc).

L’organisation des commits relève de la responsabilité du développeur. Voici quelques règles générales d’organisation:

• un commit ne doit porter que sur un sujet (un refactoring, une feature, un bugfix, …).
• un commit doit toujours permettre au projet de compiler (le projet doit toujours builder).
• suivant la taille, les tests relatifs aux modifications peuvent être dans un commit séparé.
• au sein de la même branche, le nombre de commits doit être relativement restreint (1 - 10 au maximum).
• un commit qui corrige un bug d’un commit précédent (ou porte sur le même sujet) au sein de la même branche doit être mergé avec ce dernier (rebase interactif).

Il y a également quelques contraintes particulières vérifiées dans la pipeline d’une Merge Request:

• le nombre maximum de commits par Merge Request est de 25. Au-delà, il faut soit réorganiser l’historique, soit séparer les modifications en plusieurs Merge Requests.
• il est interdit d’avoir plusieurs commits avec le même libellé. Cela signifie qu’il faut probablement réorganiser l’historique.
• il est interdit d’avoir des merge commits. Dans ce cas, la branche doit être rebasée.

Lorsque des modifications ont été faites, pour les ajouter:

git add <path>

Il existe plusieurs options à git add qui peuvent être très utiles:

• -u n’ajoute que les fichiers modifiés.
• -p permet de sélectionner précisément quelles modifications ajouter au sein des fichiers modifiés.

A ce moment, un git status affichera quels sont les fichiers qui seront dans le prochain commit:

On branch dev/doc/commits
Changes to be committed:
  (use "git restore --staged <file>..." to unstage)
        deleted:    docs/src/images/dev_sainet/github_branch_check.png
        deleted:    docs/src/images/dev_sainet/gitlab_new_branch.png
        deleted:    docs/src/images/dev_sainet/gitlab_new_branch_config.png

Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
        modified:   docs/src/050_doc_dev/dev_sainet/040_workflow.md
        modified:   docs/src/050_doc_dev/dev_sainet/040_workflow/00_awarnings.md

Une fois les modifications nécessaires ajoutées:

git commit

Le message de commit doit être clair et précis afin de décrire le but de la modification (voir ici).

Quelques options intéressantes:

• -m permet de spécifier directement le message, sans passer par l’éditeur de texte.
• --amend intègre les modifications directement dans le commit précédent (ne pas utiliser s’il n’y a pas encore de commit dans la branche !).

---

Publier sa branche

A ce stade, les modifications se trouvent dans une branche locale (donc uniquement sur votre machine). Pour pousser la branche en ligne, utiliser la commande suivante git push:

fatal: The current branch dev/doc/commits has no upstream branch.
To push the current branch and set the remote as upstream, use

    git push --set-upstream origin dev/doc/commits

De base, si la branche n’a pas été publiée, git n’a pas les informations nécessaires pour le faire et stoppe le processus, mais il fournit la commande a effectuer pour publier la branche: git push --set-upstream origin <branch>.

Attention: toute modification qui n’est pas publiée est considérée comme non existante/perdue ! La seule référence, ce sont les modifications qui se trouvent sur GitLab.

---

Soumettre une Merge Request

Une fois que vous avez publié votre branche (git push), il est temps de créer une Merge Request (MR) afin qu’elle puisse être mergée dans le master. Normalement, dès que la branche a été publiée, GitLab affiche un bouton bleu en haut à gauche pour en créer une nouvelle automatiquement.

Lors de la création, s’il n’y a qu’un seul commit, le titre est automatiquement repris, sinon il est composé à partir du nom de la branche (à ce moment-là, il faudra probablement l’adapter).

Voici quelques points à respecter:

• Le titre de la MR doit être le plus explicite possible (comme pour les commits).
• Une MR doit toujours être assignée à quelqu’un (par défaut, à vous-même).
• Ne changer l’assignement pour la relecture/review seulement lorsque la pipeline passe !
• Avant d’assigner une MR à quelqu’un d’autre, faites une relecture de vos modifications.
• La description d’une MR doit contenir un ou plusieurs changelog.
• Ajouter si nécessaire les labels de backport (par exemple MR - for 4.9.x) si les modifications doivent être mise dans des versions antérieures.

Losqu’une review est effectuée, une ou plusieurs discussions peuvent être ouvertes afin de faire des corrections/améliorations. Penser à marquer ces discussions comme résolues (resolve) avant de réassigner la MR pour une seconde passe.

---

Review d'une Merge Request

Chaque Merge Request sera revue par un autre développeur. Cela a pour but d’éviter les bugs d’inattention, les cas oubliés, vérifier que le code est de qualité et suit le standard SAINet. Le but est également que le reviewer puisse comprendre ce que l’auteur a voulu faire, et donc de diffuser la connaissance des différentes parties de l’application en interne.

Le reviewer peut donc commenter directement les lignes de code au sein même de la Merge Request et demander à l’auteur d’apporter les modifications nécessaires permettant de faire le merge ensuite.

Cela permet d’échanger directement des commentaires à propos du code de manière centralisée et d’éviter que des modifications non voulues ne viennent polluer le master. Donc tant que les différents points ouverts de la Merge Request n’ont pas été résolus, elle ne sera pas intégrée.

Note: Afin de résoudre rapidement les micro-modifications, il est possible d’éditer directement les fichiers depuis GitLab.

Personne n'aime devoir relire d'énormes pavés de code avec plein de modifications. Privilégiez plutôt de multiples petites branches (avec leur Merge Request) qui sont facilement relisibles et compréhensibles.

Le but est également de centraliser et de suivre les discussions concernant le code au sein de GitLab et d’éviter d’avoir des échanges de mails qui ne sont pas directement intégrés. Ainsi n’importe qui pourra suivre les discussions concernant certaines parties de l’application.

---

Changelog

Chaque Merge Request doit faire l’objet dans changelog. Le but de ce changelog est de pouvoir facilement lister les changements effectués entre deux versions.

Le template du changelog se choisit directement lors de la création d’une Merge Request.

Un changelog est au format YAML, encapsulé dans du Markdown. Il est donc important de garder les tags de marquage au début (```yaml, ---) et à la fin (..., ```) ! A noter qu’il est possible de mettre plusieurs blocs de changelog dans une même Merge Request.

Un autre point important est que l'indentation est déterminante. Il est donc nécessaire de bien garder les espaces en début de ligne pour que le format soit respecté.

Description du contenu d’un changelog

• level: Définit le niveau de changelog et à qui il s’adresse. Ce tag est obligatoire.

  • none: pas de changelog (pour des changements non significatifs, par exemple, correction de tests).
  • internal: changement interne n’ayant pas d’impact particulier (refactoring).
  • api: changement d’API (orienté développeurs).
  • admin: changement de configuration (par exemple, nouvelle propriété).
  • user: tout changement ayant un impact visuel ou fonctionnel.

• type: Définit le type de changement apporté par cette Merge Request.

  • bugfix: correction d’un bug.
  • feature: nouvelle fonctionnalité.
  • improvement: amélioration mineure.
  • removal: suppression.
  • other: autre type de changement.

• merge_requests: Liste des Merge Request liées à ce changement. Typiquement, si cette Merge Request corrige un bug introduit par une autre, on notera cette dernière ici.

• modules: Liste des modules qui sont affectés par les changements de la Merge Request. Généralement, seul un module sera listé.

• tasks: Liste des tâches affectées par le changement. Il faut mentionner explicitement toutes les tâches (pas de wildcard).

• requests: Liste de liens pointant vers des tickets mantis ou issue gitlab correspondant aux demandes du changement. Il est possible de mettre du texte libre également.

• description: Explications détaillées des changements. Suivant le level définit par le changelog, ce texte arrivera jusqu’à l’utilisateur final. Il doit être écrit de manière la plus neutre possible.

• delivery: Liste d’actions spécifiques à effectuer lors d’une mise à jour (par le développeur). Généralement, des requêtes SQL spécifiques.

Exemples

Amélioration à l’intérieur d’un module suite à un ticket mantis:

---
level: user
type: improvement
modules:
  - val
tasks:
  - ADR08
requests:
  - https://mantis.cross-systems.ch/mantis/view.php?id=33402
description:
  FR: |
    Nouvelle page Intervention socio-éducative.
...

Bugfix global suite à un ticket mantis:

---
level: user
type: bugfix
merge_requests:
  - 2937
modules:
  - global
tasks:
  - DEB37
requests:
  - https://mantis.cross-systems.ch/mantis/view.php?id=31221
description:
  FR: |
    Les lignes d'intégration pour les collectifs débiteurs/fournisseurs (DEB-100, FOU-100) sont indépendantes du département.
...

Modification n’ayant aucun impact:

---
level: none
...