forked from ScoDoc/DocScoDoc
ajouts et corrections
This commit is contained in:
parent
6f032db036
commit
78a51f8697
@ -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...
|
||||
|
||||
@ -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.
|
||||
@ -125,7 +125,7 @@ Note pour travailler sur VirtualBox:
|
||||
|
||||
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
|
||||
* É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)
|
||||
|
||||
@ -133,34 +133,34 @@ L'essentiel des remarques/procédures de cette section vise à obtenir une relec
|
||||
|
||||
##### Manipulations
|
||||
|
||||
Les manipulations sont décrites selons 4 phases du développement: l'installation, la mise en place, le suivi, la livraison.
|
||||
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épot git distant que vous pouvez utiliser: votre dépot personnel (`https://scodoc.org/git/<user>/<depot>.git`)
|
||||
et le dépot officiel (`https://scodoc.org/git/ScoDoc/ScoDoc.git`)
|
||||
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 depot distant, envoyez la commande:
|
||||
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/<depot>.git```
|
||||
```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 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`
|
||||
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épots connus est :
|
||||
La commande vous exposant tous les dépôts 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.
|
||||
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 ecraser les éventuels fichiers modifiés)
|
||||
pour cela (attention cela va écraser 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
|
||||
À partir de la vous pouvez modifier, tester, développer, commit.
|
||||
|
||||
##### Suivi
|
||||
|
||||
@ -168,11 +168,11 @@ Si votre développement prend plusieurs jours, il est probable que la branche pr
|
||||
|
||||
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
|
||||
- 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)
|
||||
- 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:
|
||||
Les commandes git correspondantes:
|
||||
|
||||
```
|
||||
git fetch officiel
|
||||
@ -186,19 +186,20 @@ 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`)
|
||||
Ç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`).
|
||||
|
||||
###### Etape 1 : faire l'inventaire des fichiers impliqués
|
||||
###### Étape 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)
|
||||
###### Étape 2 : passer black sur les fichiers modifiés
|
||||
|
||||
à défaut les lignes suivantes réalisent le même travail
|
||||
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)
|
||||
@ -214,23 +215,23 @@ 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
|
||||
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
|
||||
|
||||
A ce niveau là vous n'avez dans votre branche locales que les différences nécessaires à votre correctif.
|
||||
À 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
|
||||
###### É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)
|
||||
(normalement `git merge-base ma_branche officiel/master`)
|
||||
|
||||
demander un rebase interactif depuis ce point
|
||||
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)
|
||||
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
|
||||
@ -267,33 +268,33 @@ pick 83eb79e modif 2
|
||||
```
|
||||
|
||||
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)
|
||||
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:
|
||||
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
|
||||
Quand vous sortez de l'éditeur, git effectue toutes les opérations demandées
|
||||
|
||||
A 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é
|
||||
|
||||
* toutes les différeences entre officiel/master et votre branche locale sont signifiantes
|
||||
* toutes les différences entre officiel/master et votre branche locale sont signifiantes
|
||||
|
||||
###### Etape 4:
|
||||
vous pouvez maintenant pousser votre branche locale sur votre depot personnel (vers une branche de même nom):
|
||||
###### É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 auparavent il est possible que le push soit refusé (car le rebase à modifié des commits qui avaient déjà été poussés).
|
||||
Dans ce cas l'option `--force` du push vous permete de passer outre, mais assurez-vous avant d'être le seul à travailler sur cette 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
|
||||
|
||||
|
||||
@ -63,13 +63,34 @@ La documentation ci-dessous concerne la **future** version De ScoDoc.
|
||||
Elle sera accessible à l'adresse: https://scodoc.monsite.tld/ScoDoc/api/fonction
|
||||
|
||||
### 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.
|
||||
|
||||
@ -87,7 +108,9 @@ Tous les codes >= 400 indiquent que la requête n'a pas été traitée avec succ
|
||||
## Départements
|
||||
* **`departements`**
|
||||
* **Méthode:** GET
|
||||
* **Paramètres:** `viewable` (optionnel, si faux liste aussi les départements non accessibles à l'utilisateur courant), `format` (json, xml)
|
||||
* **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`
|
||||
* **Résultat:** Liste des id de départements.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user