From 33077a8ec5e24d4b21cba7791f907e1a375bf067 Mon Sep 17 00:00:00 2001 From: viennet Date: Sun, 13 Nov 2022 16:06:33 +0100 Subject: [PATCH] formattage markdown --- docs/GuideDeveloppeurs.md | 137 +++++++++++++++++++++++--------------- 1 file changed, 84 insertions(+), 53 deletions(-) diff --git a/docs/GuideDeveloppeurs.md b/docs/GuideDeveloppeurs.md index 6d444bc4e..921d285da 100644 --- a/docs/GuideDeveloppeurs.md +++ b/docs/GuideDeveloppeurs.md @@ -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": 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 @@ -160,14 +171,15 @@ la commande: ```bash git remote add nom_remote https://scodoc.org/git/ScoDoc/.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`). 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)