ScoDoc/DocScoDoc
7
2
Fork 10
Code Issues 1 Pull Requests 1 Projects Releases Wiki Activity

Merge pull request 'typos + compléments' (#14) from jmplace/DocScoDoc:doc_PR#3 into master

Browse Source 
Reviewed-on: https://scodoc.org/git/viennet/DocScoDoc/pulls/14
This commit is contained in:
Emmanuel Viennet 2021-12-30 13:34:41 +01:00
commit 7b1b33c8c4
1 changed files with 55 additions and 32 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

87
docs/GuideDeveloppeurs.md
View File

@ -129,25 +129,25 @@ Les remarques de cette section visent à obtenir une relecture facile de votre
demande d'ajout (*pull request*, dite "PR"): demande d'ajout (*pull request*, dite "PR"):
* Éviter les modifications de forme qui ne changent pas le sens du code. L'utilisation de * Éviter les modifications de forme qui ne changent pas le sens du code. L'utilisation de
[`black`](https://black.readthedocs.io/) est obligatoire: elle de normaliser la présentation [`black`](https://black.readthedocs.io/) est obligatoire : elle permet de normaliser la présentation
du code. cela évite d'e générer des différences ne représentant que des du code. cela évite de générer des différences ne représentant que des
changement de mise en forme (indentation, passages à la ligne). Cela évite changements de mise en forme (indentation, passages à la ligne). Cela évite
aussi au développeur d'avoir à y réfléchir, autant de temps gagné ! aussi au développeur d'avoir à y réfléchir, autant de temps gagné !
* Avoir un nombre d'étapes de validation faible (idéalement un seul commit pour * Avoir un nombre d'étapes de validation faible (idéalement un seul commit pour
les PR courantes (peu volumineuses). les PR courantes - peu volumineuses).
* La PR doit toujours être énoncée par rapport au dernier commit de la branche * La PR doit toujours être énoncée par rapport au dernier commit de la branche
que vous visez (en général `master` du dépôt original). que vous visez (en général `master` du dépôt original).
#### Manipulations #### Manipulations
Les manipulations sont décrites selon 4 phases du développement: l'installation, Les manipulations sont décrites selon quatre phases du développement : l'installation,
la mise en place, le suivi, la livraison. la mise en place, le suivi et la livraison.
##### l'installation ##### l'installation
Il est pratique d'avoir en ligne les deux dépôt git distant que vous pouvez Il est pratique d'avoir en ligne les deux dépôts git distants que vous pouvez
utiliser: votre dépôt personnel (`https://scodoc.org/git/<user>/<dépôt>.git`) et utiliser : votre dépôt personnel (`https://scodoc.org/git/<user>/<dépôt>.git`) et
le dépôt officiel (`https://scodoc.org/git/ScoDoc/ScoDoc.git`). le dépôt officiel (`https://scodoc.org/git/ScoDoc/ScoDoc.git`).
pour ajouter une référence (et lui donner un nom) vers un dépôt distant, entrez pour ajouter une référence (et lui donner un nom) vers un dépôt distant, entrez
@ -159,7 +159,7 @@ la commande:
Par la suite vous aurez donc une référence vers votre dépôt personnel (`perso`) Par la suite vous aurez donc une référence vers votre dépôt personnel (`perso`)
et une référence vers le dépôt officiel (`officiel`). Si vous avez initialement et une référence vers le dépôt officiel (`officiel`). Si vous avez initialement
cloné l'un des deux dépôts, la référence vers celui-ci existe et a pour nom cloné l'un des deux dépôts, la référence vers le dépot d'origine existe et a pour nom
`origin`. `origin`.
La commande vous exposant tous les dépôts connus est : La commande vous exposant tous les dépôts connus est :
@ -172,13 +172,14 @@ La commande vous exposant tous les dépôts connus est :
L'objectif de ce paragraphe est de créer une branche locale basée sur le master L'objectif de ce paragraphe est de créer une branche locale basée sur le master
du dépôt officiel et bien sur de lui donner un nom. du dépôt officiel et bien sur de lui donner un nom.
pour cela (attention cela va écraser les éventuels fichiers modifiés) : pour cela (**attention cela va écraser les éventuels fichiers modifiés**. Si vous souhaitez conserver les
modifications en cours, encadrez les lignes suivantes par `git stash` (avant) et `git stash apply` (après) :
```bash ```bash
git reset --hard officiel/master git reset --hard officiel/master
git checkout -b ma_modif git checkout -b ma_modif
``` ```
À partir de là vous pouvez modifier, tester, développer, commit. À partir de là, vous pouvez modifier, tester, développer et commit votre travail.
#### Suivi #### Suivi
@ -188,11 +189,11 @@ principale évolue pendant ce temps.
Pour garder la cohérence, il est nécessaire de réintégrer en local les 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. modifications de la branche principale. Ceci peut se faire de deux façons.
- Une fusion (`merge`) applique toutes les modifications en une seul commit). - Une fusion (`merge`) applique toutes les modifications en un seul commit).
C'est la méthode couramment utilisée. C'est la méthode couramment utilisée.
- Un `rebase` rejoue tous les commits de la nouvelle branche par dessus l'état - 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 le plus à jour de la branche principale (il en résulte un historique plus
linéaire). linéaire).
Les commandes git correspondantes : Les commandes git correspondantes :
@ -209,9 +210,9 @@ ou
#### La livraison #### La livraison
Ça y est. vous avez terminé le développement. IL n'y a plus qu'à demander Ça y est. Vous avez terminé le développement. IL n'y a plus qu'à demander
l'intégration. Ceci se fait en plusieurs étapes (vous êtes bien sûr toujours sur l'intégration. Ceci se fait en plusieurs étapes (vous êtes bien sûr toujours sur
la branche locale `ma_modif`). la branche locale `ma_modif` et toutes vos modifications ont été commitées).
##### Étape 1 : faire l'inventaire des fichiers impliqués ##### Étape 1 : faire l'inventaire des fichiers impliqués
@ -233,7 +234,8 @@ l'équivalent sous *pyCharm*).
python3 -m black $fn python3 -m black $fn
done done
``` ```
faire une première lecture rapide pour vérifier qu'il n'y ait pas de fichiers
Faire une première lecture rapide pour vérifier qu'il ne reste pas de fichiers
modifiés accidentellement. modifiés accidentellement.
Pour obtenir la modification sur un fichier spécifique (`app/fichier.py` par exemple) Pour obtenir la modification sur un fichier spécifique (`app/fichier.py` par exemple)
@ -241,26 +243,47 @@ Pour obtenir la modification sur un fichier spécifique (`app/fichier.py` par ex
git diff officiel/master app/fichier.py git diff officiel/master app/fichier.py
``` ```
Utilisateurs Windows: Vérifiez bien que les réglages de fin de ligne suivant Utilisateurs Windows : Vérifiez bien que les réglages de fin de ligne suivent
bien les règles Linux (pas de CR ou `\r` en fin de ligne juste les LF `\n`). Le bien les règles Linux (pas de retour chariot (noté CR ou `\r`) en fin de ligne mais un seul caractère line feed
cas échéant réglez votre IDE pour cela. (noté LF ou `\n`).
Le cas échéant, réglez votre IDE pour cela.
À ce niveau là vous n'avez dans votre branche locales que les différences À ce niveau là de la procèdure, vous n'avez plus dans votre branche locale que les différences strictement
nécessaires à votre correctif. nécessaires à votre correctif.
##### Étape 3: résumez tous les commits depuis le point de divergence en un seul commit ##### Étape 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 Repérez le point de divergence de votre branche locale avec officiel/master
(normalement `git merge-base ma_branche officiel/master`) (normalement `git merge-base HEAD officiel/master`)
Demander un `rebase` interactif depuis ce point : Demander un `rebase` interactif depuis ce point :
```bash ```bash
git rebase -i $(git merge-base HEAD officiel/master) git rebase -i $(git merge-base HEAD officiel/master)
```
*Explications*:
_Le rebase interactif permet d'enregistrer un suite de manipulation de commit dans un seul fichier texte._
_Le fichier texte qui reprend tels quels tous les commits concernés (et donc qui ne fait rien)_
_est préparé par la commande `-i` de la commande_ `git rebase`
_Vous pouvez ensuite modifier ce fichier dans votre editeur favori (ou pas) (à régler par `git config`) pour décrire_
_votre intention (réordonner, changer le message, fusionner, ...) sur l'ensemble des commits_
_Quand votre édition est terminée, git reprend la main est excécute chacune de vos opérations. Il est possible_
_(bien que très rare) que des conflits apparaissent à ce moment-là. Les commandes habutelles de correction accompagnées des commandes:_
```bash
git rebase --continue # pour poursuivre le processus
git rebase --abort # pour tout abandonner
```
_vous permettront de résoudre ces problèmes excptionnels_
Application:
```bash
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 Vous devez obtenir dans un éditeur de texte la liste des commits opéré depuis le
début du développement sous cette forme (c'est un exemple le nombre de lignes début du développement sous cette forme (c'est un exemple : le nombre de lignes
peut varier) : peut varier) :
```bash ```bash
@ -303,7 +326,7 @@ toutes les lignes avec la première en remplaçant le 'pick' à partir de la lig
2 par `fixup`. Optionnellement, vous pouvez reformuler le message de commit 2 par `fixup`. Optionnellement, vous pouvez reformuler le message de commit
(commande `reword` sur la première ligne). (commande `reword` sur la première ligne).
Vous construirez par exemple: Vous construirez par exemple :
```bash ```bash
reword eb8cbec Correctif: Api - gestion des formation reword eb8cbec Correctif: Api - gestion des formation
fixup 83eb79e modif 2 fixup 83eb79e modif 2
@ -312,14 +335,14 @@ fixup 83eb79e modif 2
Quand vous sortez de l'éditeur, git effectue toutes les opérations demandées. Quand vous sortez de l'éditeur, git effectue toutes les opérations demandées.
À ce niveau là de la procédure : À ce niveau-là de la procédure :
* vous avez un seul commit pour l'ensemble du correctif proposé; * vous avez un seul commit pour l'ensemble du correctif proposé ;
* toutes les différences entre officiel/master et votre branche locale sont * toutes les différences entre officiel/master et votre branche locale sont
signifiantes. signifiantes.
##### Étape 4: ##### Étape 4 :
Vous pouvez maintenant pousser votre branche locale sur votre dépôt personnel Vous pouvez maintenant pousser votre branche locale sur votre dépôt personnel
(vers une branche de même nom): (vers une branche de même nom):
@ -332,15 +355,15 @@ soit refusé (car le rebase a modifié des commits qui avaient déjà été pous
Dans ce cas l'option `--force` du push vous permette de passer outre, mais Dans ce cas l'option `--force` du push vous permette de passer outre, mais
assurez-vous avant d'être le seul à travailler sur cette branche. assurez-vous avant d'être le seul à travailler sur cette branche.
##### Etape 5: La dernière étape se passe sur le site scodoc.org/git ##### Etape 5 : La dernière étape se passe sur le site [scodoc.org/git](https://scodoc.org/git/)
* Identifiez-vous * Identifiez-vous
* Placez-vous sur la branche nouvellement créée * Placez-vous sur la branche nouvellement créée
* À l'aide de l'interface du serveur vous pouvez comparer l'état de votre * À l'aide de l'interface du serveur, vous pouvez comparer l'état de votre
branche par rapport au master officiel, et si cela vous convient de formuler branche par rapport au master officiel, et si cela vous convient, il vous reste à formuler
une demande d'intégration (pull request). une demande d'intégration (pull request). En remplissant les informations demandées.
### Tests et tests unitaires ### Tests et tests unitaires