• Contexte
• Approche, méthode
• Les données
• Agrégation et croisement
• Visualisations
• Bibliothèques utilisées
• A suivre...

• Développer des outils pour analyser les données de développement et produire de nouvelles visualisations...
• ... afin de répondre à aux bonnes questions, qu'il s'agit aussi de déterminer.
• Permettre de rejouer ces analyses et générer ces visualisations régulièrement.
• Si possible pouvoir utiliser ces outils sur d'autres logiciels voire les distribuer.

Limite imposée par Github de 5000 requêtes par heure (donc environ 4 requêtes en 3 secondes). Une requête pour lister 100 commits, 100 issues ou 100 PR. Une requête par commit, puis une requête pour lister 100 commentaires d'un commit, puis une requête par commentaire. Idem pour les issues et les PR, avec en plus leurs événements (fermeture, ....). Avec plus de 31700 commits et 13500 issues/PRs, on arrive à plusieurs dizaines de milliers de requêtes, donc plusieurs heures pour tout récupérer.

Il est évidemment inenvisageable de tout télécharger à chaque lancement. Une approche par cache ne fonctionne pas complètement: par exemple un issue ou un commentaire peut avoir été modifié et si on cache la requête qui le récupère on rate cette modification.

Solution: la récupération incrémentale.

Solution envisagée: lister les événements du dépôt depuis la dernière fois (par la date) qu'on a récupéré les données. Malheureusement, Github ne permet de récupérer qu'un nombre limité des derniers événements d'un dépôt.

Solution:

• Récupérer chaque fois la liste de tous les commits et récupérer le détail des nouveaux (et supprimer ceux qui ont disparu),
• Récupérer les issues/PR créés ou modifiés depuis la dernière fois (par la date),
• Pour ces commits et issues/PR, récupérer aussi les éléments associés (commentaires, événements, ...),
• Récupérer tous les contributeurs (avec du cache, car information pas critique, c'est surtout pour avoir les nouveaux),
• Récupérer la liste des releases.

Tout est stocké dans des fichiers JSON (1 par commit avec ses éléments attachés, idem pour chaque issue/PR et contributeur) ➩ + de 550Mo.

Des petites choses auxquelles on ne pense pas forcément de but en blanc:

• des comptes peuvent être supprimés, ils sont remplacés par le compte "ghost",
• des comptes changent de login dans le temps,
• des contributeurs n'ont pas de compte Github (notamment pour les commits avant la migration vers Github),
• des contributeurs ont plusieurs comptes Github.

➩ ajout de la possibilité de lister des contributeurs explicitement dans un fichier JSON, avec leurs différents noms et adresses mails, pour les raccrocher à un seul login. Ça a donné parfois lieu à un peu de recherches pour trouver qui se cachait derrière un login ou une adresse mail dans un commit.

Schéma partiel des données récupérées via l'API JSON:

Il existe un paquet OCaml pour faire des requêtes auprès de Github mais:

• il fallait ajouter pas mal de code pour ensuite stocker les données localement,
• la gestion du cache était à rajouter également.

J'ai préféré utiliser une de mes bibliothèques (OCaml-Ldp) qui contient un module (Http) permettant de faire des requêtes HTTP avec une politique de cache en paramètre (via un foncteur). De plus, il est possible également de passer un module pour lire des réponses dans un certain format, ici JSON, plutôt qu'en texte brut.

let mk_http conf =
  let policy_ref, cache =
      let (policy_ref, cache) = Cache.mk_cache conf.Conf.cache_dir in
      let module C = Ldp.Http.Make_cache (val cache) in
      policy_ref, (module C:Ldp.Http.Cache)
  in
  let%lwt h = Ldp_tls.make
    ~cache_impl:cache
      ~dbg:(fun s -> Statocaml.Log.debug (fun m -> m "%s" s); Lwt.return_unit)
      ()
  in
  let module H = struct
    let conf = conf
    let user = conf.user
    let repo = conf.repo
    let cache_policy_ref = policy_ref
    module HJ = Ldp.Http.Http_ct (val h)
      (struct
         type t = Yojson.Safe.t
         let ct = Ldp.Types.content_type_of_string "application/json"
         let to_string j = Yojson.Safe.to_string j
         let of_string = function
         | "" -> `Assoc []
         | s -> Yojson.Safe.from_string s
       end)
    include HJ
  end
  in
  Lwt.return (module H : Http_t)

De plus, une autre bibliothèque (Ocf) me permet de définir des structures de données pour faire lire et écrire des fichiers de configuration en JSON. En définissant des structures de données avec les mêmes champs que les réponses de Github, j'avais d'un coup ce qu'il faut pour lire les réponses de Github et les stocker en local, modulo une astuce pour accrocher les éléments attachés (commentaires, événements, ...) et qui nécessitent des requêtes supplémentaires.

type issue = {
    assignees : user list [@ocf W.list user_wrapper, []] ;
    body : string option [@ocf W.option W.string, None] ;
    closed_at : Ptime.t option [@ocf W.option ptime_wrapper, None] ;
    closed_by : user option [@ocf W.option user_wrapper, None] ;
    comments : comment list [@ocf W.list comment_wrapper, []] [@ocf.label "ignore_comments"] ;
    comments_url : Iri.t [@ocf iri_wrapper, Iri.of_string ""] ;
    ...
    user : user [@ocf user_wrapper, default_user] ;
    duration : Ptime.span option [@ocf W.(option span_wrapper), None][@ocf.label "ignore_duration"];
    ...
} [@@ocf]
(* génère un wrapper pour lire et écrire cette structure en JSON *)

Et la fonction de récupération des issues:

let issues http ?since ?limit () =
  let iri =
    let iri = issues_iri (http_user_repo http) in
    match since with
    | None -> iri
    | Some date -> iri_add_since_param iri date
  in
  let%lwt l = get_paged http ?limit iri Types.issue_wrapper in
  let%lwt l = Lwt_list.map_s (issue_with_comments http) l in
  let%lwt l = Lwt_list.map_s (issue_with_events http) l in
  let%lwt l = Lwt_list.map_s (issue_with_timeline http) l in
  let%lwt l = Lwt_list.map_s (issue_with_pull_request http) l in
  let l = List.map issue_with_duration l in
  Lwt.return l

On peut distinguer plusieurs sous-systèmes dans OCaml: typeur, parseur, bibliothèque standard, documentation, ...

Il est intéressant de pouvoir indiquer, pour chaque commit, issue et PR, le(s) sous-système(s) concerné(s), ce qui permet aussi de savoir sur quels systèmes intervient un contributeur par exemple.

Le développement d'OCaml n'utilise pas les tags de manière systématique pour indiquer les sous-systèmes concernés par un issue/PR.

Les sous-systèmes sont donc décrits dans un fichier JSON séparé, utilisant des expressions régulières pour associer un fichier donné à une liste de sous-systèmes (en pratique souvent un seul sous-système), celle associée à la première expression qui attrape le nom du fichier. On attribue à un issue/PR les sous-systèmes correspondants aux fichiers modifiés par les commits associés.

Extrait des définitions des sous-systèmes pour OCaml:

{
  "subsystems": {
    "ty": { label: "Typing", color: "#ee6363" },
    "pars": { label: "Parsing", color: "#eedd82" },
    "std": { label: "Stdlib", color: "#20b2aa" },
    "cg": { label: "Code generation", color: "#90ee90" },
    "olibs": { label: "Otherlibs", color: "#969696" },
    "test": { label: "Testing", color: "#cd853f" },
    "comp": { label: "Compiler", color: "#dda0dd" },
    "tools": { label: "Tools", color: "#00f5ff" },
    "p4": { label: "Camlp4", color: "#8ee5ee" },
    "obld": { label: "Ocamlbuild", color: "#8b008b" },
    "doc": { label: "Documentation", color: "#adff2f" },
    "bld": { label: "Build", color: "#800080" }
  },
  "rules": [
    { re_path: [ ".*\\.gif", ".*\\.tif", ".*\\.png", ".*_camltex\\.tex", "\\.github/.*",
                 "\\.git.*", "\\.ignore", "\\.ocp-indent", "\\.depend.*",
                 "\\.travis.*", "\\.cvsignore", "merlin", "\\.mailmap",
                 "ocaml-variants\\.install"
               ],
      ids: []
    },
    { re_path: ["Makefile.*", ".*/Makefile.*", "aclocal\\.m4", "configure\\.ac",
                "appveyor.*", "myocamlbuild\\.ml", "myocamlbuild_config\\.mli",
                "config/.*", "dune", "dune-project", "opam", "ocaml\\.opam",
                "cross-ios-build\\.sh"
               ],
      ids: ["bld"]
    },
...

La couleur d'un sous-système est utilisée dans certaines visualisations.

Au final, nous avons les données suivantes en entrée:

Définition de périodes à partir de toutes les dates:

• une période "All",
• une période pour chaque année entre les plus ancienne et récente dates (ici et maintenant: 1995, 1996, ... 2025),
• une période couvrant les 2 dernières années, une période couvrant les 4 dernières années,
• et une période entre chaque release.

Pour chaque contributeur et pour chaque période, on stocke:

• issues/PRs créés, revues (depuis github ou depuis le changelog), mergées (pour les PRs),
• commentaires d'issues, de PRs,
• commits,
• lignes ajoutées ou supprimées, moyennes,
• par sous-système: issues, commits, fichiers, lignes,
• combien de fois le contributeur a-t-il fait la revue de chaque autre contributeur,
• combien de fois un issue/PR du contributeur a-t-il fait l'objet de revue par chaque autre contributeur,
• ...

Agrégation au niveau global, par période également:

• nombres de commits, d'issues, de PRs (et par sous-système également),
• classement des contributeurs par activités,
• ...

Possibilité de définir des groupes de contributeurs en entrée ("Core team", "Recherche française", entreprise X ou Y, ...).

Agrégation des statistiques des contributeurs dans ces groupes et utilisation de ces groupes dans certaines visualisations.

Demande beaucoup de travail pour définir les groupes et l'appartenance des membres avec pour chacun leur date d'entrée et de sortie d'un groupe.

➩ pas fait très précisément.

L'outil génère des visualisations prédéfinies et est réutilisable pour d'autres projets.

Cependant, on peut souhaiter avoir certaines visualisations avec des paramètres différents: période, périodicité, affichage de certaines informations ou non, ...

L'outil permet d'indiquer dans un fichier des visualisations supplémentaires à générer, avec leurs paramètres. Mais plutôt que passer du temps dans une boucle consistant à changer des paramètres dans le fichier et relancer la génération, une interface graphique permet de tester plus rapidement ces paramètres:

Ensuite, un bouton copie la description de la visualisation dans le presse-papier:

{
  "w": 1358,
  "h": 922,
  "outfile": "/tmp/ab61a7.png",
  "terminal": "pngcairo",
  "title": "PR cohorts (open between 2023/01/01 and 2025/01/09)",
  "plotter": "pr_cohorts",
  "cohort_duration": 15,
  "before": (2025, 1, 9),
  "after": (2023, 1, 1)
}

Il ne reste plus qu'à la coller dans le fichier des visualisations supplémentaires passé à l'outil de génération du site (on peut aussi changer le format de sortie pour utiliser du SVG).

L'interface graphique permet également de générer directement une visualisation dans un fichier.