Adds README & NOTES

NOTES

@@ -1,3 +1,138 @@
-- creating commit at arbitrary dates :
- - git commit --date option change the authored date
- - GIT_COMMITTER_DATE env variable change the committed datetime
+############################
+# 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
+

README

@@ -0,0 +1,33 @@
+Git Office Hours (git_oh)
+-------------------------
+
+Display a ratio of commit done outside office hours per author.
+
+Dependencies
+------------
+
+- Python3 >= 3.11
+- GitPython (on debian : python3-git)
+
+Usage
+-----
+
+See git_oh --help
+
+Examples
+--------
+
+# Display ratio, per user, per month, for 1 year
+git_oh REPO_URL --from 2023-01-01 --to 2023-12-31 --group month
+
+# Display ratio of commit done in the afternoon
+git_oh REPO_URL --daystart 12:00 --daystop 00:00 --weekend NUL
+
+# Change for a 3 days weekend (on an english localized computer)
+git_oh REPO_URL --weekend fri,sat,sun
+
+# Output a CSV with detailled counters per week
+git_oh REPO_URL -f 2023-01-01 -t 2023-03-01 -g week --csv-output /tmp/output.csv
+
+# Print all commit outside office hours
+git_oh REPO_URL -f 2023-01-01 -t 2023-02-01 --verbose