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

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