DocScoDocMM/docs/GuideDeveloppeurs.md

434 lines
15 KiB
Markdown
Raw Normal View History

2020-09-21 16:30:27 +02:00
# Documentation pour les développeurs ScoDoc
Informations pour les développeurs souhaitant étendre ou modifier ScoDoc.
2021-01-28 09:47:27 +01:00
## Informations générales
2021-08-22 08:14:55 +02:00
* S'abonner aux [listes de diffusion](ListesDeDiffusion.md). Il y a aussi
un serveur Discord ouvert sur invitation aux développeur actifs. Contacter Emmanuel.
2020-09-21 16:30:27 +02:00
* [Générer de nouveaux formats de bulletins PDF](ApiGenerationBulletinsPdf.md)
* [Créer de nouveaux types de "parcours"](ApiCreationParcours.md)
2021-10-28 10:23:28 +02:00
* [API](ScoDoc9API.md) : API JSON ou XML pour interfaçage avec d'autres applications
2020-09-21 16:30:27 +02:00
* Notes diverses
* [Discussions pour la future gestion des absences](IdeesGestionAbsences.md)
* [Anciennes discussions sur la gestion des plannings](IdeesGestionPlannings.md)
2021-08-22 08:14:55 +02:00
## Développer sur ScoDoc
2021-01-28 09:47:27 +01:00
2021-09-14 12:31:16 +02:00
Quelques conseils, indications et mémos pour les développeurs sur ScoDoc version 9.
2021-01-28 09:47:27 +01:00
2021-02-01 19:55:50 +01:00
### Installation d'un serveur de développement
[Quelques conseils mouvants pour configurer votre serveur de développement](ConseilServeurDev.md)
2021-01-28 09:47:27 +01:00
### Style et formatage du code
2021-08-22 08:14:55 +02:00
L'ancienneté de la base de code a rendu le style un peu incohérent, mais cela
s'est amélioré avec ScoDoc 9 (respect PEP 8).
2021-01-28 09:47:27 +01:00
2021-09-14 12:31:16 +02:00
Le code doit être formatté avec [`black`](https://black.readthedocs.io/) avant
tout commit (configurez votre éditeur pour appeler `black` à l'enregistrement).
2021-01-28 09:47:27 +01:00
#### Documentation
On adoptera le style "Google": <https://google.github.io/styleguide/pyguide.html#383-functions-and-methods>
Exemple:
"""Description résumée de la fonction
blah blah sur la fonction
Args:
table_handle: An open smalltable.Table instance.
keys: A sequence of strings representing the key of each table
row to fetch. String keys will be UTF-8 encoded.
require_all_keys: Optional; If require_all_keys is True only
rows with values set for all keys will be returned.
Returns:
A dict mapping keys to the corresponding table row data
fetched. Each row is represented as a tuple of strings. For
example:
{b'Serak': ('Rigel VII', 'Preparer'),
b'Zim': ('Irk', 'Invader'),
b'Lrrr': ('Omicron Persei 8', 'Emperor')}
"""
### Git
2021-12-30 09:58:58 +01:00
Le dépôt est <https://scodoc.org/git/viennet/ScoDoc>
2021-01-28 09:47:27 +01:00
La branche `master` est celle de ScoDoc 9. La branche `Scodoc7` est l'ancienne
(jusqu'à septembre 2021) version en production.
2021-01-28 09:47:27 +01:00
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
basique:
2021-01-28 09:47:27 +01:00
# Créer une branche
# si besoin (travail en cours), utiliser git stash avant
git checkout master
git branch hotfix
git checkout hotfix
... dev, test ...
git add ...
git commit -m "fixed ..."
git checkout master
git merge hotfix
git branch -d hotfix
# publication
# éventuellement: git stash pop
#### Mettre à jour votre branche
Vous travaillez dans votre branche `ma_branche`. Pour lui appliquer les mises à
jour de `master` (remote):
2021-12-30 10:55:32 +01:00
```bash
2021-01-28 09:47:27 +01:00
git pull origin master
2021-12-30 10:55:32 +01:00
```
2021-01-28 09:47:27 +01:00
#### Commandes utiles, en vrac
* `git log -L:fonction_python:fichier.py`
2021-01-29 13:41:40 +01:00
* Commits locaux: `git log @{u}..`
2021-01-28 09:47:27 +01:00
#### Refactoring
Lint tous les fichiers modifiés:
2021-12-30 10:55:32 +01:00
```bash
2021-01-28 09:47:27 +01:00
git status | grep modified | grep .py | awk '{print $2}' | xargs pylint -E
2021-12-30 10:15:20 +01:00
```
2021-01-28 09:47:27 +01:00
Restore les modes au besoin (SAMBA les changent parfois):
2021-12-30 10:55:32 +01:00
```bash
2021-01-28 09:47:27 +01:00
git diff -p -R --no-color | grep -E "^(diff|(old|new) mode)" --color=never | git apply
2021-12-30 10:15:20 +01:00
```
2021-02-18 08:36:22 +01:00
Affiche les variables non définies dans un fichier:
2021-12-30 10:55:32 +01:00
```bash
2021-02-18 08:36:22 +01:00
pylint --disable=all -e E sco_parcours_dut.py | grep undefined-variable | awk '{print $4;}' | sort | uniq | tr -d \'
2021-12-30 10:15:20 +01:00
```
2021-02-18 08:36:22 +01:00
Prépare un sed pour renommer les variables non définies:
2021-12-30 10:55:32 +01:00
```bash
2021-02-18 08:36:22 +01:00
for f in *.py
do
pylint --disable=all -e E "$f" | grep undefined-variable | awk '{print "sed -i .bak s/"$4"/scu."$4"/ '$f'";}' | sort | uniq | tr -d \'
done
2021-12-30 10:15:20 +01:00
```
2021-02-18 08:36:22 +01:00
2021-08-22 08:14:55 +02:00
Note pour travailler sur VirtualBox:
addgroup scodoc vboxsf
2021-12-30 10:15:20 +01:00
### Préparation d'une PR (Pull Request)
2021-12-21 15:56:23 +01:00
2021-12-30 10:15:20 +01:00
#### Principes généraux
2021-12-21 15:56:23 +01:00
2021-12-30 10:15:20 +01:00
Les remarques de cette section visent à obtenir une relecture facile de votre
demande d'ajout (*pull request*, dite "PR"):
2021-12-21 15:56:23 +01:00
2021-12-30 10:15:20 +01:00
* Éviter les modifications de forme qui ne changent pas le sens du code. L'utilisation de
2021-12-30 11:28:45 +01:00
[`black`](https://black.readthedocs.io/) est obligatoire : elle permet de normaliser la présentation
du code. cela évite de générer des différences ne représentant que des
changements de mise en forme (indentation, passages à la ligne). Cela évite
2021-12-30 10:15:20 +01:00
aussi au développeur d'avoir à y réfléchir, autant de temps gagné !
2021-12-21 15:56:23 +01:00
2021-12-30 10:15:20 +01:00
* Avoir un nombre d'étapes de validation faible (idéalement un seul commit pour
2021-12-30 11:28:45 +01:00
les PR courantes - peu volumineuses).
2021-12-21 15:56:23 +01:00
2021-12-30 10:15:20 +01:00
* 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).
2021-12-21 15:56:23 +01:00
2021-12-30 10:15:20 +01:00
#### Manipulations
2021-12-21 15:56:23 +01:00
2021-12-30 11:28:45 +01:00
Les manipulations sont décrites selon quatre phases du développement : l'installation,
la mise en place, le suivi et la livraison.
2021-12-21 15:56:23 +01:00
2021-12-30 10:15:20 +01:00
##### l'installation
2021-12-30 11:28:45 +01:00
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
2021-12-30 10:15:20 +01:00
le dépôt officiel (`https://scodoc.org/git/ScoDoc/ScoDoc.git`).
2021-12-21 15:56:23 +01:00
2021-12-30 10:15:20 +01:00
pour ajouter une référence (et lui donner un nom) vers un dépôt distant, entrez
la commande:
2021-12-21 15:56:23 +01:00
2021-12-30 10:55:32 +01:00
```bash
2021-12-30 10:15:20 +01:00
git remote add nom_remote https://scodoc.org/git/ScoDoc/<dépôt>.git
```
2021-12-21 15:56:23 +01:00
2021-12-30 10:15:20 +01:00
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
2021-12-30 11:28:45 +01:00
cloné l'un des deux dépôts, la référence vers le dépot d'origine existe et a pour nom
2021-12-30 10:15:20 +01:00
`origin`.
2021-12-21 15:56:23 +01:00
2021-12-30 09:58:58 +01:00
La commande vous exposant tous les dépôts connus est :
2021-12-30 10:55:32 +01:00
```bash
2021-12-30 10:15:20 +01:00
git remote -v
```
2021-12-21 15:56:23 +01:00
2021-12-30 10:15:20 +01:00
#### Mise en place
2021-12-21 15:56:23 +01:00
2021-12-30 10:15:20 +01:00
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.
2021-12-21 15:56:23 +01:00
2021-12-30 11:28:45 +01:00
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) :
2021-12-21 15:56:23 +01:00
2021-12-30 10:55:32 +01:00
```bash
git reset --hard officiel/master
git checkout -b ma_modif
2021-12-21 15:56:23 +01:00
```
2021-12-30 11:28:45 +01:00
À partir de là, vous pouvez modifier, tester, développer et commit votre travail.
2021-12-21 15:56:23 +01:00
2021-12-30 10:15:20 +01:00
#### Suivi
2021-12-21 15:56:23 +01:00
2021-12-30 10:15:20 +01:00
Si votre développement prend plusieurs jours, il est probable que la branche
principale évolue pendant ce temps.
2021-12-21 15:56:23 +01:00
2021-12-30 10:15:20 +01:00
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.
2021-12-21 15:56:23 +01:00
2021-12-30 11:28:45 +01:00
- Une fusion (`merge`) applique toutes les modifications en un seul commit).
2021-12-30 10:15:20 +01:00
C'est la méthode couramment utilisée.
2021-12-21 15:56:23 +01:00
2021-12-30 10:15:20 +01:00
- Un `rebase` rejoue tous les commits de la nouvelle branche par dessus l'état
2021-12-30 11:28:45 +01:00
le plus à jour de la branche principale (il en résulte un historique plus
2021-12-30 10:15:20 +01:00
linéaire).
2021-12-21 15:56:23 +01:00
2021-12-30 10:55:32 +01:00
Les commandes git correspondantes :
2021-12-21 15:56:23 +01:00
2021-12-30 10:55:32 +01:00
```bash
git fetch officiel
git merge officiel/master
2021-12-21 15:56:23 +01:00
```
ou
2021-12-30 10:55:32 +01:00
```bash
git fetch officiel
git rebase officiel/merge
2021-12-21 15:56:23 +01:00
```
2021-12-30 10:15:20 +01:00
#### La livraison
2021-12-21 15:56:23 +01:00
2021-12-30 11:28:45 +01:00
Ça y est. Vous avez terminé le développement. IL n'y a plus qu'à demander
2021-12-30 10:15:20 +01:00
l'intégration. Ceci se fait en plusieurs étapes (vous êtes bien sûr toujours sur
2021-12-30 11:28:45 +01:00
la branche locale `ma_modif` et toutes vos modifications ont été commitées).
2021-12-21 15:56:23 +01:00
2021-12-30 10:15:20 +01:00
##### Étape 1 : faire l'inventaire des fichiers impliqués
2021-12-21 15:56:23 +01:00
2021-12-30 10:55:32 +01:00
```bash
git fetch officiel/master
git diff --name-only officiel/master
2021-12-21 15:56:23 +01:00
```
2021-12-30 10:15:20 +01:00
##### Étape 2 : passer black sur les fichiers modifiés
2021-12-21 15:56:23 +01:00
2021-12-30 10:15:20 +01:00
Cette étape est automatique avec les bons réglages sous VSCode (pas trouvé
l'équivalent sous *pyCharm*).
2021-12-30 09:58:58 +01:00
2021-12-30 10:55:32 +01:00
À défaut les lignes suivantes réalisent le même travail :
2021-12-21 15:56:23 +01:00
2021-12-30 10:55:32 +01:00
```bash
for fn in $(git diff --name-only officiel/master)
do
python3 -m black $fn
done
2021-12-21 15:56:23 +01:00
```
2021-12-30 11:28:45 +01:00
Faire une première lecture rapide pour vérifier qu'il ne reste pas de fichiers
2021-12-30 10:15:20 +01:00
modifiés accidentellement.
2021-12-21 15:56:23 +01:00
2021-12-30 10:15:20 +01:00
Pour obtenir la modification sur un fichier spécifique (`app/fichier.py` par exemple)
2021-12-30 10:55:32 +01:00
```bash
git diff officiel/master app/fichier.py
2021-12-21 15:56:23 +01:00
```
2021-12-30 11:28:45 +01:00
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.
2021-12-21 15:56:23 +01:00
2021-12-30 11:28:45 +01:00
À ce niveau là de la procèdure, vous n'avez plus dans votre branche locale que les différences strictement
2021-12-30 10:15:20 +01:00
nécessaires à votre correctif.
2021-12-21 15:56:23 +01:00
2021-12-30 11:28:45 +01:00
##### Étape 3 : résumez tous les commits depuis le point de divergence en un seul commit
2021-12-21 15:56:23 +01:00
Repérez le point de divergence de votre branche locale avec officiel/master
2021-12-30 11:28:45 +01:00
(normalement `git merge-base HEAD officiel/master`)
2021-12-21 15:56:23 +01:00
2021-12-30 10:55:32 +01:00
Demander un `rebase` interactif depuis ce point :
2021-12-21 15:56:23 +01:00
2021-12-30 10:55:32 +01:00
```bash
git rebase -i $(git merge-base HEAD officiel/master)
2021-12-30 13:40:30 +01:00
```
2021-12-30 11:28:45 +01:00
*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_
2021-12-30 13:40:30 +01:00
_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 :_
2021-12-30 11:28:45 +01:00
```bash
git rebase --continue # pour poursuivre le processus
git rebase --abort # pour tout abandonner
2021-12-21 15:56:23 +01:00
```
2021-12-30 13:40:30 +01:00
_vous permettront de résoudre ces problèmes exceptionnels_.
2021-12-30 11:28:45 +01:00
Application:
2021-12-21 15:56:23 +01:00
2021-12-30 11:28:45 +01:00
```bash
git rebase -i $(git merge-base HEAD officiel/master)
```
2021-12-30 10:15:20 +01:00
Vous devez obtenir dans un éditeur de texte la liste des commits opéré depuis le
2021-12-30 11:28:45 +01:00
début du développement sous cette forme (c'est un exemple : le nombre de lignes
2021-12-30 10:55:32 +01:00
peut varier) :
2021-12-21 15:56:23 +01:00
2021-12-30 10:55:32 +01:00
```bash
2021-12-21 15:56:23 +01:00
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.
#
```
2021-12-30 10:15:20 +01:00
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).
2021-12-21 15:56:23 +01:00
2021-12-30 11:28:45 +01:00
Vous construirez par exemple :
2021-12-30 10:55:32 +01:00
```bash
2021-12-21 15:56:23 +01:00
reword eb8cbec Correctif: Api - gestion des formation
fixup 83eb79e modif 2
...
```
2021-12-30 10:15:20 +01:00
Quand vous sortez de l'éditeur, git effectue toutes les opérations demandées.
2021-12-21 15:56:23 +01:00
2021-12-30 11:28:45 +01:00
À ce niveau-là de la procédure :
2021-12-21 15:56:23 +01:00
2021-12-30 11:28:45 +01:00
* vous avez un seul commit pour l'ensemble du correctif proposé;
2021-12-21 15:56:23 +01:00
2021-12-30 10:15:20 +01:00
* toutes les différences entre officiel/master et votre branche locale sont
signifiantes.
2021-12-21 15:56:23 +01:00
2021-12-30 11:28:45 +01:00
##### Étape 4 :
2021-12-30 10:15:20 +01:00
Vous pouvez maintenant pousser votre branche locale sur votre dépôt personnel
(vers une branche de même nom):
2021-12-21 15:56:23 +01:00
2021-12-30 10:55:32 +01:00
```bash
git push --set-upstream perso ma_branche
2021-12-21 15:56:23 +01:00
```
2021-12-30 10:15:20 +01:00
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.
2021-12-21 15:56:23 +01:00
2021-12-30 11:28:45 +01:00
##### Etape 5 : La dernière étape se passe sur le site [scodoc.org/git](https://scodoc.org/git/)
2021-12-21 15:56:23 +01:00
* Identifiez-vous
* Placez-vous sur la branche nouvellement créée
2021-12-30 11:28:45 +01:00
* À 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
2021-12-30 13:40:30 +01:00
une demande d'intégration (*pull request*). En remplissant les informations demandées.
2021-12-21 15:56:23 +01:00
2021-12-30 13:40:30 +01:00
## Tests et tests unitaires
2021-08-22 08:14:55 +02:00
Voir [TestsScoDoc](TestsScoDoc.md)
## Cache Redis
Certains objets couteux à calculer sont cachés. Depuis ScoDoc 9, on utilise
Redis, via `flask-caching`.
2021-08-22 08:14:55 +02:00
Au besoin, mémo:
- client ligne de commande: `https://redis.io/topics/rediscli`
- afficher les clés: `redis-cli KEYS '*'`
- `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.
2021-08-22 08:14:55 +02:00
- `flask clear-cache` efface le cache Redis.
2021-01-28 09:47:27 +01:00
2022-01-08 00:58:33 +01:00
## 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`.
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
/bin/rm -rf venv # ou mv ...
python3 -m venv venv
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
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
```
Note: la mise à jour par `apt` recrée le virtualenv à chaque fois.
2021-01-28 09:47:27 +01:00
2021-01-29 13:41:40 +01:00
## Roadmap
Sujets **prioritaires** en 2021:
2020-09-21 16:30:27 +02:00
- Modernisation du code: Flask, Python 3: achevé août 2021.
2021-01-29 13:41:40 +01:00
- 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.
2021-01-29 13:41:40 +01:00
- Redéfinition API et interface mobile simplifiée.
Autres sujets:
- [voir les tickets](https://scodoc.org/git/viennet/ScoDoc/issues)