iziram/DocAssiduites
1
0
Fork 0
forked from ScoDoc/DocScoDoc
Code Issues Pull Requests Packages Projects Releases Wiki Activity

formattage markdown

Browse Source
This commit is contained in:
Emmanuel Viennet 2022-11-13 16:06:33 +01:00
parent 7c439f3b4f
commit 33077a8ec5
1 changed files with 84 additions and 53 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

137
docs/GuideDeveloppeurs.md
View File

@ -1,28 +1,28 @@
# Documentation pour les développeurs ScoDoc # Documentation pour les développeurs ScoDoc
Informations pour les développeurs souhaitant étendre ou modifier ScoDoc. Informations pour les développeurs souhaitant étendre ou modifier ScoDoc.
## Informations générales ## Informations générales
* S'abonner aux [listes de diffusion](ListesDeDiffusion.md). Il y a aussi * S'abonner aux [listes de diffusion](ListesDeDiffusion.md). Il y a aussi
un serveur Discord ouvert sur invitation aux développeur actifs. Contacter Emmanuel. un serveur Discord ouvert sur invitation aux développeur actifs. Contacter Emmanuel.
* [Générer de nouveaux formats de bulletins PDF](ApiGenerationBulletinsPdf.md) * [Générer de nouveaux formats de bulletins PDF](ApiGenerationBulletinsPdf.md)
* [Créer de nouveaux types de "parcours"](ApiCreationParcours.md) * [Créer de nouveaux types de "parcours"](ApiCreationParcours.md)
* [API](ScoDoc9API.md) : API JSON ou XML pour interfaçage avec d'autres applications * [API](ScoDoc9API.md) : API JSON ou XML pour interfaçage avec d'autres applications
* Notes diverses * Notes diverses
* [Discussions pour la future gestion des absences](IdeesGestionAbsences.md) * [Discussions pour la future gestion des absences](IdeesGestionAbsences.md)
* [Anciennes discussions sur la gestion des plannings](IdeesGestionPlannings.md) * [Anciennes discussions sur la gestion des plannings](IdeesGestionPlannings.md)
## Développer sur ScoDoc ## Développer sur ScoDoc
Quelques conseils, indications et mémos pour les développeurs sur ScoDoc version 9. Quelques conseils, indications et mémos pour les développeurs sur ScoDoc version 9.
### Installation d'un serveur de développement ### Installation d'un serveur de développement
[Quelques conseils pour configurer votre serveur de développement](ConseilServeurDev.md) [Quelques conseils pour configurer votre serveur de développement](ConseilServeurDev.md)
### Style et formatage du code ### Style et formatage du code
L'ancienneté de la base de code a rendu le style un peu incohérent, mais cela L'ancienneté de la base de code a rendu le style un peu incohérent, mais cela
s'est nettement amélioré avec ScoDoc 9 (respect PEP 8). s'est nettement amélioré avec ScoDoc 9 (respect PEP 8).
@ -30,6 +30,7 @@ Le code DOIT être formatté avec [`black`](https://black.readthedocs.io/) avant
tout commit (configurez votre éditeur pour appeler `black` à l'enregistrement). tout commit (configurez votre éditeur pour appeler `black` à l'enregistrement).
#### Documentation #### Documentation
On pourra adopter le style "Google": <https://google.github.io/styleguide/pyguide.html#383-functions-and-methods> On pourra adopter le style "Google": <https://google.github.io/styleguide/pyguide.html#383-functions-and-methods>
Exemple: Exemple:
@ -64,6 +65,7 @@ distribués (*releases*). Les développements ont lieu sur d'autres branches
La branche `Scodoc7` était l'ancienne (jusqu'à septembre 2021) version de ScoDoc. La branche `Scodoc7` était l'ancienne (jusqu'à septembre 2021) version de ScoDoc.
Ci-dessous quelques pense-bête qui peuvent servir. Ci-dessous quelques pense-bête qui peuvent servir.
#### Hot fixes (internes) #### Hot fixes (internes)
Pour les développeurs internes (écriture sur le dépôt master), un exemple Pour les développeurs internes (écriture sur le dépôt master), un exemple
@ -84,13 +86,14 @@ basique illustrant le cycle de développement:
# éventuellement: git stash pop # éventuellement: git stash pop
Dans la plupart des cas, on travaillera sur son propre dépot (clone du dépt Dans la plupart des cas, on travaillera sur son propre dépôt (clone du dépt
origine), et on proposera une *pull request* (PR, *demande d'ajout* en français). origine), et on proposera une *pull request* (PR, *demande d'ajout* en français).
#### Mettre à jour votre branche #### Mettre à jour votre branche
Quand vous travaillez dans votre branche `ma_branche`, pour lui appliquer les Quand vous travaillez dans votre branche `ma_branche`, pour lui appliquer les
mises à jour de `master` (remote), faire: mises à jour de `master` (remote), faire:
```bash ```bash
git pull origin master git pull origin master
``` ```
@ -103,18 +106,19 @@ mises à jour de `master` (remote), faire:
#### Refactoring #### Refactoring
Lint tous les fichiers modifiés: Lint tous les fichiers modifiés:
```bash ```bash
git status | grep modified | grep .py | awk '{print $2}' | xargs pylint -E git status | grep modified | grep .py | awk '{print $2}' | xargs pylint -E
``` ```
Restore les modes au besoin (SAMBA les changent parfois):
```bash
git diff -p -R --no-color | grep -E "^(diff|(old|new) mode)" --color=never | git apply
```
Affiche les variables non définies dans un fichier: Affiche les variables non définies dans un fichier:
```bash ```bash
pylint --disable=all -e E sco_parcours_dut.py | grep undefined-variable | awk '{print $4;}' | sort | uniq | tr -d \' pylint --disable=all -e E sco_parcours_dut.py | grep undefined-variable | awk '{print $4;}' | sort | uniq | tr -d \'
``` ```
Prépare un sed pour renommer les variables non définies: Prépare un sed pour renommer les variables non définies:
```bash ```bash
for f in *.py for f in *.py
do do
@ -122,6 +126,13 @@ Prépare un sed pour renommer les variables non définies:
done done
``` ```
Restore les modes au besoin (SAMBA les changent parfois):
```bash
git diff -p -R --no-color | grep -E "^(diff|(old|new) mode)" --color=never | git apply
```
Note pour travailler sur VirtualBox: Note pour travailler sur VirtualBox:
addgroup scodoc vboxsf addgroup scodoc vboxsf
@ -160,14 +171,15 @@ la commande:
```bash ```bash
git remote add nom_remote https://scodoc.org/git/ScoDoc/<dépôt>.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`) 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 le dépot d'origine existe et a pour nom cloné l'un des deux dépôts, la référence vers le dépôt 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 :
```bash ```bash
git remote -v git remote -v
``` ```
@ -184,6 +196,7 @@ modifications en cours, encadrez les lignes suivantes par `git stash` (avant) et
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 et commit votre travail. À partir de là, vous pouvez modifier, tester, développer et commit votre travail.
#### Suivi #### Suivi
@ -194,12 +207,12 @@ 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 un 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 principale (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 :
@ -207,7 +220,9 @@ Les commandes git correspondantes :
git fetch officiel git fetch officiel
git merge officiel/master git merge officiel/master
``` ```
ou ou
```bash ```bash
git fetch officiel git fetch officiel
git rebase officiel/merge git rebase officiel/merge
@ -243,18 +258,20 @@ l'équivalent sous *pyCharm*).
Faire une première lecture rapide pour vérifier qu'il ne reste 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):
```bash ```bash
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 suivent Utilisateurs Windows : Vérifiez bien que les réglages de fin de ligne suivent
bien les règles Linux (pas de retour chariot (noté CR ou `\r`) en fin de ligne mais un seul caractère line feed bien les règles Linux (pas de retour chariot (noté CR ou `\r`) en fin de ligne
(noté LF ou `\n`). mais un seul caractère line feed (noté LF ou `\n`). Le cas échéant, réglez
Le cas échéant, réglez votre IDE pour cela. votre IDE pour cela.
À ce niveau là de la procèdure, vous n'avez plus dans votre branche locale que les différences strictement À ce niveau là de la procédure, vous n'avez plus dans votre branche locale que
nécessaires à votre correctif. les différences strictement 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
@ -267,17 +284,20 @@ Demander un `rebase` interactif depuis ce point :
git rebase -i $(git merge-base HEAD officiel/master) git rebase -i $(git merge-base HEAD officiel/master)
``` ```
*Explications*: *Explications*: Le rebase interactif permet d'enregistrer un suite de
_Le rebase interactif permet d'enregistrer un suite de manipulation de commit dans un seul fichier texte._ manipulation de commit dans un seul fichier texte. Le fichier texte qui reprend
_Le fichier texte qui reprend tels quels tous les commits concernés (et donc qui ne fait rien)_ tels quels tous les commits concernés (et donc qui ne fait rien) est préparé par
_est préparé par la commande `-i` de la commande_ `git rebase` 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_ Vous pouvez ensuite modifier ce fichier dans votre éditeur favori (ou pas) (à
_votre intention (réordonner, changer le message, fusionner, ...) sur l'ensemble des commits_ 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 exécute chacune de vos
opérations. Il est possible (bien que très rare) que des conflits apparaissent
à ce moment-là. Les commandes habituelles de correction accompagnées des
commandes :
_Quand votre édition est terminée, git reprend la main est exécute chacune de vos opérations. Il est possible_
_(bien que très rare) que des conflits apparaissent à ce moment-là. Les_
_commandes habituelles de correction accompagnées des commandes :_
```bash ```bash
git rebase --continue # pour poursuivre le processus git rebase --continue # pour poursuivre le processus
git rebase --abort # pour tout abandonner git rebase --abort # pour tout abandonner
@ -289,6 +309,7 @@ Application:
```bash ```bash
git rebase -i $(git merge-base HEAD officiel/master) 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) :
@ -333,6 +354,7 @@ toutes les lignes avec la première en remplaçant le 'pick' à partir de la lig
(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
@ -349,6 +371,7 @@ Quand vous sortez de l'éditeur, git effectue toutes les opérations demandées.
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):
@ -368,8 +391,9 @@ assurez-vous avant d'être le seul à travailler sur cette branche.
* 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, il vous reste à formuler branche par rapport au master officiel, et si cela vous convient, il vous
une demande d'intégration (*pull request*). En remplissant les informations demandées. reste à formuler une demande d'intégration (*pull request*). En remplissant
les informations demandées.
## Tests et tests unitaires ## Tests et tests unitaires
@ -382,23 +406,24 @@ Redis, via `flask-caching`.
Au besoin, mémo: Au besoin, mémo:
- client ligne de commande: `https://redis.io/topics/rediscli` - client ligne de commande: `https://redis.io/topics/rediscli`
- afficher les clés: `redis-cli KEYS '*'` - afficher les clés: `redis-cli KEYS '*'`
- `redis-cli TTL key` affiche le TTL d'un clé, -1 si infini. - `redis-cli TTL key` affiche le TTL d'un clé, -1 si infini.
- `redis-cli -r -1 -i 3 KEYS '*_NT_*'` surveille certaines clés (ici _NT_), - `redis-cli -r -1 -i 3 KEYS '*_NT_*'` surveille certaines clés (ici _NT_),
affiche toutes les 3 secondes. affiche toutes les 3 secondes.
- `flask clear-cache` efface le cache Redis. - `flask clear-cache` efface le cache Redis.
## Re-création du virtualenv ## Re-création du virtualenv
ScoDoc est livré avec un "virtualenv", qui contient tous les modules python ScoDoc est livré avec un "virtualenv", qui contient tous les modules python
nécessaires. Il se trouve sous `/opt:scodoc/venv`. nécessaires. Il se trouve sous `/opt/scodoc/venv`.
Si vous souhaitez repartir de zéro, tester de nouvelles versions de certaines Si vous souhaitez repartir de zéro, tester de nouvelles versions de certaines
bibliothèques, ou autres expériences de ce genre, vous pouvez le récréer ainsi: bibliothèques, ou autres expériences de ce genre, vous pouvez le récréer ainsi:
```bash ```bash
# en tant qu'utilisateur scodoc # en tant qu'utilisateur scodoc
cd /opt/scodoc cd /opt/scodoc
@ -407,17 +432,23 @@ bibliothèques, ou autres expériences de ce genre, vous pouvez le récréer ain
source venv/bin/activate source venv/bin/activate
pip install wheel pip install wheel
``` ```
Puis soit vous installez les versions "officielles" (testées) Puis soit vous installez les versions "officielles" (testées)
``` ```
pip install -r requirements-3.9.txt pip install -r requirements-3.9.txt
``` ```
Soit vous prenez les version les plus à jour disponibles. Une façon rapide de
Soit vous prenez les versions les plus à jour disponibles. Une façon rapide de
faire ceci est: faire ceci est:
```bash ```bash
cut -d= -f 1 requirements-3.9.txt | xargs pip install cut -d= -f 1 requirements-3.9.txt | xargs pip install
``` ```
à adapter selon vos objectifs. à adapter selon vos objectifs.
Pour régénérer le fichier indiquant la liste des paquets: Pour régénérer le fichier indiquant la liste des paquets:
```bash ```bash
pip freeze > requirements-3.9.txt pip freeze > requirements-3.9.txt
``` ```
@ -427,13 +458,13 @@ Note: la mise à jour par `apt` recrée le virtualenv à chaque fois.
## Roadmap ## Roadmap
Sujets **prioritaires** en 2021-2022: Sujets **prioritaires** en 2021-2022:
- Modernisation du code: Flask, Python 3: achevé août 2021. - Modernisation du code: Flask, Python 3: achevé août 2021.
- Prise en compte du Bachelor (BUT): SAÉ, suivi compétences, validations des - Prise en compte du Bachelor (BUT): SAÉ, suivi compétences, validations des
blocs, UE, semestres selon la cadrage et l'arrêté Licence Pro 2020. (achevé blocs, UE, semestres selon la cadrage et l'arrêté Licence Pro 2020. (achevé
avec ScoDoc 9.2 puis complété en 9.3 et 9.4) avec ScoDoc 9.2 puis complété en 9.3 et 9.4)
- Définition et développement nouvelle API (achevé avec 9.3 en juillet 22) - Définition et développement nouvelle API (achevé avec 9.3 en juillet 22)
Autres sujets: Autres sujets:
- [voir les tickets](https://scodoc.org/git/viennet/ScoDoc/issues) - [voir les tickets](https://scodoc.org/git/viennet/ScoDoc/issues)