DocScoDoc/docs/GuideDeveloppeurs.md

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. 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
• Créer de nouveaux types de "parcours"
• API : API JSON ou XML pour interfaçage avec d'autres applications
• Notes diverses
  • Discussions pour la future gestion des absences
  • Anciennes discussions sur la gestion des plannings

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 mouvants pour configurer votre serveur de développement

Style et formatage du code

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).

Le code doit être formatté avec black avant tout commit (configurez votre éditeur pour appeler black à l'enregistrement).

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

Le dépot 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.

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:

# 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):

git pull origin master

Commandes utiles, en vrac

• git log -L:fonction_python:fichier.py
• Commits locaux: git log @{u}..

Refactoring

Lint tous les fichiers modifiés:

git status | grep modified | grep .py | awk '{print $2}' | xargs pylint -E

Restore les modes au besoin (SAMBA les changent parfois):

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:

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:

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

Note pour travailler sur VirtualBox:

addgroup scodoc vboxsf

Préparation d'un PR

Principes généraux

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

• Avoir un nombre d'étapes de validation faible (idéalement un seul commit pour les PR courantes (peu volumineuses)

• La PR doit toujours être énoncé par rapport au dernier commit de la branche master officielle

Manipulations

Les manipulations sont décrites selons 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)

pour ajouter une référence (et lui donner un nom) vers un depot distant, envoyez la commande:

git remote add nom_remote https://scodoc.org/git/ScoDoc/<depot>.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`

la commande vous exposant tous les dépots 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.

pour cela (attention cela va ecraser 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

Suivi

Si votre développement prend plusieurs jours, il est probable que la branche 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 modifs en une seul commit). c est la méthode courament 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)

les commandes git correspondantes:

git fetch officiel
git merge officiel/master

ou

git fetch officiel
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)

Etape 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)

à défaut les lignes suivantes réalisent le même travail

for fn in $(git diff --name-only officiel/master)
do
  python3 -m black $fn
done 

faire une première lecture rapide pour vérifier qu'il n'y ait pas de fichiers modifiés accidentellement.

pour obtenir la modification sur un fichier spécifique (app/fichier.py par exemple)

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

A 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

Repérez le point de divergence de votre branche locale avec officiel/master (normalement git merge-base ma_branche officiel/master)

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)

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.
#
~

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)

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

A 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

Etape 4:

vous pouvez maintenant pousser votre branche locale sur votre depot 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.

Etape 5: La dernière étape se passe sur le site scodoc.org/git

• Identifiez-vous

• 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 de formuler une demande d'intégration (pull request)

Tests

Voir TestsScoDoc

Cache Redis

Certains objets couteux à calculer sont cachés. Depuis ScoDoc 9, on utilise Redis, via flask-caching.

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.

• flask clear-cache efface le cache Redis.

Roadmap

Sujets prioritaires en 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.

• Redéfinition API et interface mobile simplifiée.

Autres sujets:

• voir les tickets