DocAssiduites/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](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](ScoDocAPI.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 7.x et 8.

### Installation d'un serveur de développement
[Quelques conseils mouvants 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'améliore avec ScoDoc 9 (respect PEP 8).

Le code doit être formatté avec [`black`](https://black.readthedocs.io/) 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 (pas encore en production). La branche `Scodoc7` est l'ancienne (actuelle jusqu'à septembre 2021) en production.

Ci-dessous quelques pense-bête qui peuvent servir.
#### Hot fixes (internes)

Pour les développeurs internes (écriture sur le dépot 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](TestsScoDoc.md)

## Cache Redis

Certains objets couteux à calculer sont cachés. Depuyis 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_), affche 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'arêté Licence Pro 2020.

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

Autres sujets:
  - [voir les tickets](https://scodoc.org/git/viennet/ScoDoc/issues)