a

Reviewed-on: https://scodoc.org/git/viennet/DocScoDoc/pulls/13

docs/GuideConfig.md

@@ -135,6 +135,7 @@ Commands:
   clear-cache                    Clear ScoDoc cache This cache (currently...
   create-dept                    Create new departement
   create-role                    Create a new role
+  delete-role                    Delete a role       
   delete-dept                    Delete existing departement
   dumphelp
   edit-role                      Add [-a] and/or remove [-r] a permission...

docs/GuideDeveloppeurs.md

@@ -56,7 +56,7 @@ Exemple:
 
 ### Git
 
-Le dépot est <https://scodoc.org/git/viennet/ScoDoc>
+Le dépôt est <https://scodoc.org/git/viennet/ScoDoc>
 
 La branche `master` est celle de ScoDoc 9. La branche `Scodoc7` est l'ancienne
 (jusqu'à septembre 2021) version en production.
@@ -119,6 +119,191 @@ 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:
+
+* Éviter les modifications de forme sans substance sémantique. L'utilisation de [`black`](https://black.readthedocs.io/) 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 selon 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épôt git distant que vous pouvez 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`)
+
+pour ajouter une référence (et lui donner un nom) vers un dépôt distant, envoyez la commande:
+
+```git remote add nom_remote https://scodoc.org/git/ScoDoc/<dépôt>.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 dépôt officiel (`officiel`). L'un des deux
+si vous avez initialement cloné l'un des deux dépôts, la référence vers celui-ci existe et a pour nom `origin`.
+
+La commande vous exposant tous les dépôts connus est :
+
+`git remote -v`
+
+##### Mise en place
+
+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.
+
+pour cela (attention cela va écraser les éventuels fichiers modifiés)
+
+```
+git reset --hard officiel/master
+git checkout -b ma_modif 
+```
+À partir de la vous pouvez modifier, tester, développer, 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 modifications en une seul commit). C'est la méthode couramment 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
+
+Ç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 la branche locale `ma_modif`).
+
+###### Étape 1 : faire l'inventaire des fichiers impliqués
+
+```
+git fetch officiel/master
+git diff --name-only officiel/master
+```
+
+###### Étape 2 : passer black sur les fichiers modifiés
+
+Cette étape est automatique avec les bons réglages sous VSCode (pas trouvé l'équivalent 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 échéant réglez votre IDE pour cela
+
+À ce niveau là vous n'avez dans votre branche locales que les différences nécessaires à votre correctif.
+
+###### É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
+(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éveloppement sous cette 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 <commit> = use commit
+# r, reword <commit> = use commit, but edit the commit message
+# e, edit <commit> = use commit, but stop for amending
+# s, squash <commit> = use commit, but meld into previous commit
+# f, fixup [-C | -c] <commit> = 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 <command> = run command (the rest of the line) using shell
+# b, break = stop here (continue rebase later with 'git rebase --continue')
+# d, drop <commit> = remove commit
+# l, label <label> = label current HEAD with a name
+# t, reset <label> = reset HEAD to a label
+# m, merge [-C <commit> | -c <commit>] <label> [# <oneline>]
+# .       create a merge commit using the original merge commit's
+# .       message (or the oneline, if no original merge commit was
+# .       specified); use -c <commit> to reword the commit message
+#
+# These lines can be re-ordered; they are executed from top to bottom.
+#
+# If you remove a line here THAT COMMIT WILL BE LOST.
+#
+# However, if you remove everything, the rebase will be aborted.
+#
+~
+```
+
+vous pouvez réorganiser tous les commits (changer l'ordre, fusionner) en changeant la commande pick au début de chaque ligne
+l idée ici est de fusionner toutes les lignes avec la première en remplaçant le 'pick' à partir de la ligne 2 par `fixup`.
+optionnellement, vous pouvez reformuler le message de commit (commande `reword` sur la première ligne).
+
+Vous construirez par exemple:
+```
+reword eb8cbec Correctif: Api - gestion des formation
+fixup 83eb79e modif 2
+...
+```
+
+Quand vous sortez de l'éditeur, git effectue toutes les opérations demandées
+
+À ce niveau là de la procédure:
+
+* vous avez un seul commit pour l'ensemble du correctif proposé
+
+* toutes les différences entre officiel/master et votre branche locale sont signifiantes
+
+###### Étape 4:
+Vous pouvez maintenant pousser votre branche locale sur votre dépôt personnel (vers une branche de même nom):
+
+```
+git push --set-upstream perso ma_branche
+```
+
+Si vous avez déjà fait cette opération auparavant il est possible que le push soit refusé (car le rebase a modifié des commits qui avaient déjà été poussés).
+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.
+
+###### Etape 5: La dernière étape se passe sur le site scodoc.org/git
+
+* Identifiez-vous
+
+* Placez-vous sur la branche nouvellement créée
+
+* À 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 une demande d'intégration (pull request)
+
 ### Tests
 
 Voir [TestsScoDoc](TestsScoDoc.md)

docs/ScoDoc9API.md

@@ -65,13 +65,34 @@ Elle sera accessible à l'adresse: https://scodoc.monsite.tld/ScoDoc/api/fonctio
 L'ensemble des routes sont visible via la commande suivante : ``flask routes | grep /ScoDoc/api``
 
 ### Authentification
- TODO décrire procédure d'authentification et tokens jwt.
 
-Lors de votre authentification (_connection avec login et mdp_) à Scodoc, il vous sera attribué un token jwt (_généré automatiquement_) vous permettant d'utiliser l'api suivant les droits correspondant à votre session.
+Lors de votre authentification (_connection avec login et mdp_) à Scodoc, il
+vous sera attribué un jeton (token jwt _généré automatiquement_) vous permettant
+d'utiliser l'api suivant les droits correspondant à votre session.
 
+Pour obtenir le jeton, il faut un compte sur ScoDoc (`user_name`et `password`).
+Les autorisations et rôles sont gérés exactement comme pour l'application. 
+
+Exemple avec `curl` (un outil en ligne de commande présent sur la plupart des
+systèmes):
+  
+    curl -u user_name:password --request POST  https://SERVEUR/ScoDoc/api/tokens 
+
+où `SERVEUR` est l'adresse (IP ou nom) de votre serveur.
+La réponse doit ressembler à ceci:
+```
+{
+  "token": "LuXXxk+i74TXYZZl8MulgbiCGmVHXXX"
+}
+```
+
+Vous trouverez dans `/opt/scodoc/tests/api/exemple-api-basic.py` un exemple
+complet en python d'interrogation de l'API.
 
 ### Codes HTTP
-Chaque appel à l'API donne lieu à une réponse retournant un code spécifique en fonction du résultat obtenu. L'analyse de ce code vous permet de vous assurer que la requête a été traitée avec succès.
+Chaque appel à l'API donne lieu à une réponse retournant un code spécifique en
+fonction du résultat obtenu. L'analyse de ce code vous permet de vous assurer
+que la requête a été traitée avec succès.
 
 Tous les codes >= 400 indiquent que la requête n'a pas été traitée avec succès par nos serveurs.
 
@@ -89,9 +110,17 @@ Tous les codes >= 400 indiquent que la requête n'a pas été traitée avec succ
 ##  Départements
   * **`departements`** 
     * **Méthode:** GET
+<<<<<<< HEAD
+    * **Paramètres:** `viewable` (optionnel, si faux liste aussi les
+      départements non accessibles à l'utilisateur courant), `format` (json,
+      xml)
+    * **Routes:** `/api/departements`
+    * **Exemple d'utilisation:** `/api/departements`
+=======
     * **Paramètres:** `viewable` (optionnel, si faux liste aussi les départements non accessibles à l'utilisateur courant), `format` (json, xml)
     * **Routes:** `/ScoDoc/api/departements`
     * **Exemple d'utilisation:** `/ScoDoc/api/departements`
+>>>>>>> ca20ff89e1a0f9b1e3c55ceac8799ed9155ea512
     * **Résultat:** Liste des id de départements.
     * **Exemple de résultat:** `[id_1, id_2, id_3, ...]`