From a9f12ab0dfdb5b8445933ecfc6c0ec48c0312b0b Mon Sep 17 00:00:00 2001 From: Jean-Marie PLACE Date: Wed, 29 Dec 2021 22:26:36 +0100 Subject: [PATCH] =?UTF-8?q?compl=C3=A9ment=20=C3=A0=20la=20doc:=20pull=20r?= =?UTF-8?q?equest?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/GuideDeveloppeurs.md | 184 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 184 insertions(+) diff --git a/docs/GuideDeveloppeurs.md b/docs/GuideDeveloppeurs.md index 673bce593..bd0f6d7d2 100644 --- a/docs/GuideDeveloppeurs.md +++ b/docs/GuideDeveloppeurs.md @@ -119,6 +119,190 @@ Note pour travailler sur VirtualBox: addgroup scodoc vboxsf +#### Préparation d'un PR + +##### Principes généraux + +L'essentiel des remarques/procédures de cette section vise à obtenir une relecture facile des modifications: + +* Eviter les modifications de forme sans substance sémantique. L'utilisation de blackify permet de normaliser la présentation du code + +* Avoir un nombre d'étapes de validation faible (idéalement un seul commit pour les PR courantes (peu volumineuses) + +* La PR doit toujours être énoncé par rapport au dernier commit de la branche master officielle + +##### Manipulations + +Les manipulations sont décrites selons 4 phases du développement: l'installation, la mise en place, le suivi, la livraison. + +###### l'installation +Il est pratique d'avoir en ligne les deux dépot git distant que vous pouvez utiliser: votre dépot personnel (`https://scodoc.org/git//.git`) +et le dépot officiel (`https://scodoc.org/git/ScoDoc/ScoDoc.git`) + +pour ajouter une référence (et lui donner un nom) vers un depot distant, envoyez la commande: + +```git remote add nom_remote https://scodoc.org/git/ScoDoc/.git``` + +Par la suite vous aurez donc une référence vers votre dépôt personnel (`perso`) et une référence vers le depot officiel (`officiel`). L'un des deux +si vous avez iniitalement cloné l'un des deux dépots, la référence vers celui-ci existe et a pour nom òrigin` + +la commande vous exposant tous les dépots connus est : + +`git remote -v` + +##### Mise en place + +l'objectf de ce paragraphe est de créer une branche locale basée sur le master du dépot officiel et bien sur de lui donner un nom. + +pour cela (attention cela va ecraser les éventuels fichiers modifiés) + +``` +git reset --hard officiel/master +git checkout -b ma_modif +``` +A partir de la vous pouvez modifier, tester, developper, commit + +##### Suivi + +Si votre développement prend plusieurs jours, il est probable que la branche principale évolue pendant ce temps. + +Pour garder la cohérence, il est nécessaire de réintégrer en local les modifications de la branche principale. Ceci peut se faire de deux façons. + +une fusion (merge) applique toutes les modifs en une seul commit). c est la méthode courament utilisée + +un rebase rejoue tous les commits de la nouvelle branche par dessus l'état le plus à jour de la branche principal (il en résulte un historique plus linéaire) + +les commandes git correspondantes: + +``` +git fetch officiel +git merge officiel/master +``` +ou +``` +git fetch officiel +git rebase officiel/merge +``` + +##### La livraison + +Ca y est. vous avez terminé le développment. IL n'y a plus qu'à demander l'intégration. Ceci se fait en plusieurs étapes (vous êtes bien sur toujours sur la branche locale `ma_modif`) + +###### Etape 1 : faire l'inventaire des fichiers impliqués + +``` +git fetch officiel/master +git diff --name-only officiel/master +``` +###### Etape 2 : passer black sur les fichiers modifiés + +Cette étape est automatique avec les bons réglages sous VSCode (pas trouvé l'équivallent sous pyCharm) + +à défaut les lignes suivantes réalisent le même travail + +``` +for fn in $(git diff --name-only officiel/master) +do + python3 -m black $fn +done +``` +faire une première lecture rapide pour vérifier qu'il n'y ait pas de fichiers modifiés accidentellement. + +pour obtenir la modification sur un fichier spécifique (`app/fichier.py` par exemple) +``` +git diff officiel/master app/fichier.py +``` + +Utilisateurs Windows: +Vérifiez bien que les réglages de fin de ligne suivant bien les règles linux (pas de CR ou \r en fin de ligne juste les LF \n). +Le cas écéheant réglez votre IDE pour cela + +A ce niveau là vous n'avez dans votre branche locales que les différences nécessaires à votre correctif. + +###### Etape 3: résumez tous les commits depuis le point de divergence en un seul commit + +Repérez le point de divergence de votre branche locale avec officiel/master +(normalement git merge-base ma_branche officiel/master) + +demander un rebase interactif depuis ce point + +``` +git rebase -i $(git merge-base HEAD officiel/master) +``` + +vous devez obtenir dans un éditeur de texte la liste des commits opéré depuis le début du développment sou scette forme (c'est un exemple le nombre de lignes peut varier) + +``` +pick eb8cbec modif 1 +pick 83eb79e modif 2 + +# Rebase 5ffd074..83eb79e onto 5ffd074 (2 commands) +# +# Commands: +# p, pick = use commit +# r, reword = use commit, but edit the commit message +# e, edit = use commit, but stop for amending +# s, squash = use commit, but meld into previous commit +# f, fixup [-C | -c] = like "squash" but keep only the previous +# commit's log message, unless -C is used, in which case +# keep only this commit's message; -c is same as -C but +# opens the editor +# x, exec = run command (the rest of the line) using shell +# b, break = stop here (continue rebase later with 'git rebase --continue') +# d, drop = remove commit +# l, label