git_oh/NOTES.txt

############################
# Notes de développement : #
############################

++++++++++++++++++
+ Grandes étapes +
++++++++++++++++++

1) Recherche et choix d'une bibliothèque

Dès la réception du mail, j'ai pris le temps de rechercher une bibliothèque
permettant d'interagir avec un dépot git.
La première bibliothèque que j'ai trouvé ( GitPython ) m'a convenu pour
plusieurs raisons :
- elle est packagée par Debian (disponible sous le nom python3-git)
- les tests ont été concluants :
  - possibilité de récupérer la liste de tous les commit d'un dépot (quelque
    soit la branche)
  - possibilité de récupérer la liste de tous les commit d'un dépot distant
    après un fetch (sans avoir à cloner le dépot)


2) Réflexion sur la définition des "horaires de travail"

Une définition simple a été retenue (pour s'en tenir au sujet) :
- Une heure de début et une heure de fin pour les jours travaillés
- Une liste de jours non travaillés (le week-end)

Le choix a été fait de ne pas tenir compte du fuseau horaire récupéré :
considérer que la journée de travail commence à la même heure quelque soit
le fuseau horaire semble être la meilleur méthode pour prévenir les
situations de burn-out.

Ce choix implique que les heures de début et de fin devraient être définies
sans fuseau horaire.


3) Choix d'une méthode pour utiliser la bibliothèque

J'ai passé un certain temps à réfléchir à la méthode qui me conviendrait le
mieux pour récupérer les commits d'un dépot.
L'objectif étant de récupérer un iterateur sur des commits pour permettre un
traitement en flux et éviter de stocker l'ensemble des donnée de l'ensemble
des commits d'un dépot.

Rapidement il s'est avéré qu'il faudrait sûrement créer un dépot temporaire
avec comme idée de faire :
- git init
- git add remote URL
- git fetch
- itérer sur les commit
- supprimer le dépot temporaire

Même si l'idée d'écrire une classe dédiée ne me plaisait pas à priori, c'est
la méthode la plus sûre que j'ai trouvé pour :
- garantir la suppression du dépot temporaire
- garantir la non suppression du dépot temporaire tant qu'une référence à un
  commit existe (la récupération de certaines informations des commits est
  faite a l'appel de la méthode : si le dépot n'existe plus on ne peut pas
  récupérer l'info)

C'est pour cette raison que l'utilisation de contextlib.contextmanager a été
abandonnée (on pourrait garder une référence sur un commit en dehors du bloc
'with')


4) Premiers tests unitaires

Une première série de test a été écrite pour valider/tester :
- les méthodes de récupération des commits
- la fonction qui vérifie si un moment est "hors horaire" ou non


5) Réflexions sur l'UI et les fonctionnalités

Le choix a été fait d'une CLI et d'utiliser argparse pour gérer les
arguments.

Les premiers arguments ajoutés ont été ceux permettant de définir les
horaires de travail : horaire de début/fin de journée, liste des jours de
weekend.

Deux sorties ont été envisagées :
- une sortie "CLI" lisible dans un terminal
- une sortie CSV pour permettre d'envoyer le résultat à un autre programme
  pour des traitements supplémentaires

Rapidement, une fonctionnalité m'a semblé essentielle pour rendre le script
utile : indiquer une période que l'on veut analyser (ajout des
arguments --from DATEHEURE --to DATEHEURE ).

Ne prévoyant pas d'implémenter de cache, le programme ne sera pas pratique à
lancer plusieurs fois de suite. Il m'a donc semblé important de proposer des
méthodes d'aggrégations permettant d'observer plus précisément le nombre de
commit "hors horaire".

Le script bénéficie donc d'une option --group 'week' ou --group 'month' qui
permet de produire le ratio des commits hors horaire pour les périodes
indiquées (en plus du total).


6) Implémentation de la sortie

Une fonction d'aggrégation (par utilisateur et, optionnellement par une des
deux périodes de temps proposées) a été écrite.

Les deux fonctions de sorties : CLI ou CSV ont aussi été écrites. L'argument
permettant de choisir d'écrire un fichier CSV a été ajouté (--csv-output FILE).

La décision a été prise d'ajouter une seconde ligne par utilisateur au tableau
affiché en "sortie CLI", une ligne affichant le nombre total de commit :
10% de 10 commit ne représente pas la même surcharge que 10% de 300 commit.


7) Packaging

J'ai pris la décision de mettre en place un packaging minimal pour le script :
Un setup.py sur lequel s'appuyer pour construire un paquet debian.


+++++++++++++++
+ Temps passé +
+++++++++++++++

La durée totale serait compliquée à évaluer, mais malgrès une semaine
chargée, j'ai pu y consacrer différents moments tout au long de la semaine.


+++++++++++++++++++++++++++
+ Difficultés rencontrées +
+++++++++++++++++++++++++++

- Essayer d'avoir un résultat aussi simple que lisible tout en étant aussi
  complet et utilisable que possible
- Se limiter dans les fonctionnalités pour le rendre plus pratique
- Le packaging
- Une semaine chargée