forked from ScoDoc/DocScoDoc
formattage markdown
This commit is contained in:
parent
7c439f3b4f
commit
33077a8ec5
@ -1,28 +1,28 @@
|
||||
# Documentation pour les développeurs ScoDoc
|
||||
|
||||
|
||||
Informations pour les développeurs souhaitant étendre ou modifier ScoDoc.
|
||||
|
||||
## Informations générales
|
||||
|
||||
* S'abonner aux [listes de diffusion](ListesDeDiffusion.md). Il y a aussi
|
||||
un serveur Discord ouvert sur invitation aux développeur actifs. Contacter Emmanuel.
|
||||
* [Générer de nouveaux formats de bulletins PDF](ApiGenerationBulletinsPdf.md)
|
||||
* [Créer de nouveaux types de "parcours"](ApiCreationParcours.md)
|
||||
* [API](ScoDoc9API.md) : API JSON ou XML pour interfaçage avec d'autres applications
|
||||
* Notes diverses
|
||||
* [Discussions pour la future gestion des absences](IdeesGestionAbsences.md)
|
||||
* [Anciennes discussions sur la gestion des plannings](IdeesGestionPlannings.md)
|
||||
|
||||
* S'abonner aux [listes de diffusion](ListesDeDiffusion.md). Il y a aussi
|
||||
un serveur Discord ouvert sur invitation aux développeur actifs. Contacter Emmanuel.
|
||||
* [Générer de nouveaux formats de bulletins PDF](ApiGenerationBulletinsPdf.md)
|
||||
* [Créer de nouveaux types de "parcours"](ApiCreationParcours.md)
|
||||
* [API](ScoDoc9API.md) : API JSON ou XML pour interfaçage avec d'autres applications
|
||||
* Notes diverses
|
||||
* [Discussions pour la future gestion des absences](IdeesGestionAbsences.md)
|
||||
* [Anciennes discussions sur la gestion des plannings](IdeesGestionPlannings.md)
|
||||
|
||||
## Développer sur ScoDoc
|
||||
|
||||
Quelques conseils, indications et mémos pour les développeurs sur ScoDoc version 9.
|
||||
|
||||
### Installation d'un serveur de développement
|
||||
|
||||
[Quelques conseils pour configurer votre serveur de développement](ConseilServeurDev.md)
|
||||
|
||||
### Style et formatage du code
|
||||
|
||||
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).
|
||||
|
||||
@ -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).
|
||||
|
||||
#### Documentation
|
||||
|
||||
On pourra adopter le style "Google": <https://google.github.io/styleguide/pyguide.html#383-functions-and-methods>
|
||||
|
||||
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.
|
||||
|
||||
Ci-dessous quelques pense-bête qui peuvent servir.
|
||||
|
||||
#### Hot fixes (internes)
|
||||
|
||||
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
|
||||
|
||||
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).
|
||||
|
||||
#### Mettre à jour votre branche
|
||||
|
||||
Quand vous travaillez dans votre branche `ma_branche`, pour lui appliquer les
|
||||
mises à jour de `master` (remote), faire:
|
||||
|
||||
```bash
|
||||
git pull origin master
|
||||
```
|
||||
@ -103,18 +106,19 @@ mises à jour de `master` (remote), faire:
|
||||
#### Refactoring
|
||||
|
||||
Lint tous les fichiers modifiés:
|
||||
|
||||
```bash
|
||||
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:
|
||||
|
||||
```bash
|
||||
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:
|
||||
|
||||
```bash
|
||||
for f in *.py
|
||||
do
|
||||
@ -122,6 +126,13 @@ Prépare un sed pour renommer les variables non définies:
|
||||
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:
|
||||
|
||||
addgroup scodoc vboxsf
|
||||
@ -164,10 +175,11 @@ la commande:
|
||||
|
||||
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
|
||||
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`.
|
||||
|
||||
La commande vous exposant tous les dépôts connus est :
|
||||
|
||||
```bash
|
||||
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 checkout -b ma_modif
|
||||
```
|
||||
|
||||
À partir de là, vous pouvez modifier, tester, développer et commit votre travail.
|
||||
|
||||
#### 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
|
||||
modifications de la branche principale. Ceci peut se faire de deux façons.
|
||||
|
||||
- Une fusion (`merge`) applique toutes les modifications en un seul commit).
|
||||
C'est la méthode couramment utilisée.
|
||||
- Une fusion (`merge`) applique toutes les modifications en un 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 principale (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 principale (il en résulte un historique plus
|
||||
linéaire).
|
||||
|
||||
Les commandes git correspondantes :
|
||||
|
||||
@ -207,7 +220,9 @@ Les commandes git correspondantes :
|
||||
git fetch officiel
|
||||
git merge officiel/master
|
||||
```
|
||||
|
||||
ou
|
||||
|
||||
```bash
|
||||
git fetch officiel
|
||||
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
|
||||
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
|
||||
git diff officiel/master app/fichier.py
|
||||
```
|
||||
|
||||
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
|
||||
(noté LF ou `\n`).
|
||||
Le cas échéant, réglez votre IDE pour cela.
|
||||
bien les règles Linux (pas de retour chariot (noté CR ou `\r`) en fin de ligne
|
||||
mais un seul caractère line feed (noté LF ou `\n`). Le cas échéant, réglez
|
||||
votre IDE pour cela.
|
||||
|
||||
À ce niveau là de la procèdure, vous n'avez plus dans votre branche locale que les différences strictement
|
||||
nécessaires à votre correctif.
|
||||
À ce niveau là de la procédure, vous n'avez plus dans votre branche locale que
|
||||
les différences strictement nécessaires à votre correctif.
|
||||
|
||||
##### É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)
|
||||
```
|
||||
|
||||
*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`
|
||||
*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_
|
||||
Vous pouvez ensuite modifier ce fichier dans votre éditeur 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 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
|
||||
git rebase --continue # pour poursuivre le processus
|
||||
git rebase --abort # pour tout abandonner
|
||||
@ -289,6 +309,7 @@ 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
|
||||
début du développement sous cette forme (c'est un exemple : le nombre de lignes
|
||||
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).
|
||||
|
||||
Vous construirez par exemple :
|
||||
|
||||
```bash
|
||||
reword eb8cbec Correctif: Api - gestion des formation
|
||||
fixup 83eb79e modif 2
|
||||
@ -349,6 +371,7 @@ Quand vous sortez de l'éditeur, git effectue toutes les opérations demandées.
|
||||
signifiantes.
|
||||
|
||||
##### Étape 4 :
|
||||
|
||||
Vous pouvez maintenant pousser votre branche locale sur votre dépôt personnel
|
||||
(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
|
||||
|
||||
* À 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
|
||||
une demande d'intégration (*pull request*). En remplissant les informations demandées.
|
||||
branche par rapport au master officiel, et si cela vous convient, il vous
|
||||
reste à formuler une demande d'intégration (*pull request*). En remplissant
|
||||
les informations demandées.
|
||||
|
||||
## Tests et tests unitaires
|
||||
|
||||
@ -382,23 +406,24 @@ Redis, via `flask-caching`.
|
||||
|
||||
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_),
|
||||
affiche toutes les 3 secondes.
|
||||
- `redis-cli -r -1 -i 3 KEYS '*_NT_*'` surveille certaines clés (ici _NT_),
|
||||
affiche toutes les 3 secondes.
|
||||
|
||||
- `flask clear-cache` efface le cache Redis.
|
||||
- `flask clear-cache` efface le cache Redis.
|
||||
|
||||
## Re-création du virtualenv
|
||||
|
||||
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
|
||||
bibliothèques, ou autres expériences de ce genre, vous pouvez le récréer ainsi:
|
||||
|
||||
```bash
|
||||
# en tant qu'utilisateur 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
|
||||
pip install wheel
|
||||
```
|
||||
|
||||
Puis soit vous installez les versions "officielles" (testées)
|
||||
|
||||
```
|
||||
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:
|
||||
|
||||
```bash
|
||||
cut -d= -f 1 requirements-3.9.txt | xargs pip install
|
||||
```
|
||||
à adapter selon vos objectifs.
|
||||
|
||||
Pour régénérer le fichier indiquant la liste des paquets:
|
||||
|
||||
```bash
|
||||
pip freeze > requirements-3.9.txt
|
||||
```
|
||||
@ -427,13 +458,13 @@ Note: la mise à jour par `apt` recrée le virtualenv à chaque fois.
|
||||
## Roadmap
|
||||
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
|
||||
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)
|
||||
- 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é
|
||||
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:
|
||||
- [voir les tickets](https://scodoc.org/git/viennet/ScoDoc/issues)
|
||||
|
||||
Loading…
Reference in New Issue
Block a user