Introduction

• Présentation du projet ;
• Fonctionnement collaboratif d'utilitR ;
• Collaboration sur Github ;
• Le rôle de l'intégration continue pour se concentrer sur le contenu ;
• Notre retour d'expérience ;

1. Présentation du projet

Une démarche collaborative et open source

• Projet entièrement open source ( InseeFrLab) :
  • Tous les codes sources sont disponibles sur Github ;
  • licence ouverte et peu contraignante (Licence Ouverte 2.0).

• Démarche collaborative impliquant plus de 25 contributeurs :

  • dispersés dans toute la France ;
  • issus de plusieurs institutions du SSP.
  • Un immense merci à eux ! 👏

• Organisation horizontale, sur le modèle de Wikipedia :

  • relecture par les pairs ;
  • validation collégiale ;
  • discussions publiques, toutes contributions bienvenues.

Tout le monde peut contribuer à utilitR !

1. Présentation du projet

Des choix techniques au service de la qualité

• Une documentation pensée pour le statisticien :

  • Recommandations adaptées au contexte de travail des agents du service statistique public ;
  • Exemples sur données réelles Insee (grâce au package doremifasol) ;
  • Documentation entièrement reproductible
  • Insee: exemples mobilisables dans AUS.

• Processus de publication à l'état de l'art :

  • Plusieurs outputs (site web , livre PDF ) avec les mêmes codes sources ;
  • Publication automatique à chaque modification des fichiers sources.

1. Présentation du projet

Une démarche collaborative et open source

• Acculturation à des outils favorisant la reproductibilité et la pérennité, au-delà de l'usage de :

  • Docker ;
  • Git ;
  • Github .

• La résolution des défis techniques ont permis des évolutions de l'écosystème R Markdown :

  • Amélioration du package pagedown pour produire la brochure pdf ;
  • Correction d'un bug dans le package rmarkdown pour produire le site internet.

Le projet utilitR est un laboratoire qui préfigure les évolutions des méthodes de travail des statisticiens.

1. Présentation du projet

La communauté des contributeurs

Rejoignez l'aventure utilitR !

1. Présentation du projet

Diffusion de la documentation

La documentation est diffusée sous trois formes :

• un site internet (www.utilitr.org) ;
• chaque fiche est disponible en format A4 sur le site internet ;
• l'intégralité de la documentation en format pdf.

Il est envisagé que le site internet soit actualisé en continu, tandis que la brochure pdf serait publiée de façon ponctuelle et millésimée (mais produite de manière automatique).

utilitR est en évolution constante, venez proposer vos idées ou donner un coup de main !

2. Fonctionnement du projet

Organisation du projet

Le projet utilitR est un projet collaboratif, horizontal, open source et ouvert à tous, auquel tous les agents peuvent contribuer.

• Cinq principes détaillés dans le manifeste : transparence, ouverture, bienveillance, exigence et reproductibilité.

• Organisation sans hiérarchie :

  • Un groupe de contributeurs ✒️ (environ 25), parmi lesquels deux coordinateurs ;
  • Un comité de parrainage composé de managers 👼: Benoît Rouppert, Arnaud Degorre, Patrick Sillard, Sébastien Roux.

• Les travaux sont menés selon les méthodes de développement logiciel (pull requests, issues) ;

• La marche à suivre pour contribuer est détaillée dans le guide de contribution.
  
  Vous pouvez rejoindre l'équipe de contributeurs à tout moment.

2. Fonctionnement du projet

Organisation du projet

Le comité de parrainage
Les contributeurs

2. Fonctionnement du projet

Les 5 principes du projet utilitR

• Transparence : l'ensemble du projet est librement accessible sur le dépôt Github, sous licence libre ;
• Ouverture : toute personne qui le souhaite peut rejoindre le projet à tout moment. Les modalités de contribution peuvent prendre différentes formes, détaillées dans le guide des contributeurs ;
• Bienveillance : toutes les idées, initiatives et propositions sont les bienvenues, et les contributeurs veillent à se soutenir les uns les autres ;
• Exigence : les modifications de la documentation sont systématiquement soumises à une revue par les contributeurs du projet et ne sont acceptées que lorsqu'elles rencontrent une large approbation ;
• Reproductibilité : les exemples développés dans la documentation doivent être reproductibles.

Ces principes sont exposées dans un Manifeste exposant la philosophie du projet

2. Fonctionnement du projet

L'architecture du projet

• Les contributeurs collaborent par l'intermédiaire du dépôt Github du projet https://www.github.com/inseefrlab/utilitr.

2. Fonctionnement du projet

L'architecture du projet

• Des scripts automatiques créent l'environnement informatique de production de la documentation et vérifient que les codes sources ne contiennent pas de bug.

2. Fonctionnement du projet

L'architecture du projet

• La documentation est déployée automatiquement en plusieurs formats ;
• Mais il est nécessaire de tester les évolutions avant leur déploiement.

2. Fonctionnement du projet

L'architecture du projet

• Chaque contribution est déployée sur un site temporaire pour vérification ;
• Seule la version validée sera sur www.book.utilitr.org.

2. Fonctionnement du projet

Une approche au service de la reproductibilité et de la qualité

C'est le dépôt Github d'utilitR qui centralise tout le fonctionnement du projet. Il propose :

• Un environnement informatique complet et reproductible pour produire la documentation (image Docker ) ;

• Des scripts d' intégration continue qui vérifient que les contributions ne comportent pas d'erreur de programmation, et que les exemples sont bien reproductibles ;

• Des scripts de déploiement continu qui compilent la documentation et déploient le site internet à chaque modification de la branche master ;

• Un site de prévisualisation (via Netlify) sur lequel les contributeurs peuvent voir les modifications qu'ils apportent au site, sans que le site public ne soit modifié.

3. Quelle collaboration sur Github ?

Objectif : permettre à tous de contribuer

• Plusieurs modalités de contribution proposées pour offrir légèreté, flexibilité et simplicité ;

• Les contributions les plus simples sont possibles via une interface graphique ;

  • Le bouton Edit this page sur www.book.utilitr.org permet d'utiliser l'interface visuelle Github pour proposer une modification d'une fiche (pull request automatiquement créée).

  • Les issues sont des fils de discussion qui permettent des débats et échanges sur tous les sujets :

    • signaler un bug,
    • proposer une nouvelle fiche,
    • proposer un nouvel exemple,
    • participer à un débat sur un package...

3. Quelle collaboration sur Github ?

Objectif : permettre à tous de contribuer

• Pour ajouter des éléments plus substantiels (nouvelles fiches, ajout de paragraphe, évolution de la tuyauterie...), il est possible d'ouvrir des pull requests.
• Les contributeurs s'entraident pour acquérir la maîtrise des outils.

• Il n'est pas nécessaire de bien connaître Git et Github pour contribuer au projet ;
• Contribuer au projet permet de se familiariser avec les méthodes de l'open source qui renforcent la fiabilité des projets.

3. Quelle collaboration sur Github ?

Démonstration

Démonstration !

3. Quelle collaboration sur Github ?

Méthode de travail

• On a choisi le mode de travail le plus léger (Github Flow) ;
• Cependant, les seuls personnes ayant droit d'écriture sur InseeFrLab/utilitR sont les coordinateurs (mainteneurs) ;
• Les contributeurs travaillent sur des copies du dépôt principal (forks) et soumettent les changements à partir de ces copies ;
• Lorsqu'une modification proposée par un contributeur est validée par les autres contributeurs, elle est intégrée au dépôt principal par les coordinateurs.

Ce mode de travail est exportable à un environnement interne Gitlab

4. Intégration continue

Avantages de l'automatisation des processus :

Chaque action sur Github déclenche des scripts pour construire, tester et déployer la mise à jour de la documentation:

• allège le travail des coordinateurs et des contributeurs ;
• assure un environnement plus reproductible ;
• assure la cohérence entre les différents formats ;
• facilite le repérage des erreurs ;
• permet aux contributeurs d'ignorer les détails techniques de la production de la documentation et de se concentrer uniquement sur le fond.

4. Intégration continue

R Markdown, un langage pour les gouverner tous

• Les codes sources de la documentation prennent la forme de fichiers R Markdown, qui rassemblent les textes et les exemples de codes ;

• R compile ces codes sources de deux manières :

  • Production d'un site internet grâce au package blogdown ;
  • Production d'un livre en format A4 grâce au package pagedown ;
  • De plus, l'utilisation de paged.js permet de transformer chaque page du site internet en un chapitre paginé prêt à être imprimé.

• Les modèles de document reposent sur les technologies Web standards (CSS et Javascript) et sont organisés sous la forme d'un package.

Utiliser les outils les plus appropriés pour réaliser une tâche donnée (compilation en site web, en PDF...).

5. Retour d'expérience

Git et Github : un écosystème efficace

• Une unique source de vérité avec au même endroit :
  • le contenu validé ;
  • le contenu en cours de rédaction ;

• Pas de mail pour s'échanger des fichiers ou des informations ;
  • Les informations importantes sont archivées directement dans le projet, pas dans une boîte mail ;

• Organiser le travail collaboratif de façon ouverte et transparente :
  • tout le monde peut proposer des modifications (correction coquille, rédaction fiche, etc.) ;
  • tout le monde peut donner son avis.

• Pas besoin d'être un expert Git pour contribuer à un projet collaboratif :
  • Besoin d'un ou deux facilitateurs ou coach Git ;
  • Proposer des modalités de contribution facilitées (bouton Edit this page sur le site)
  • Intérêt d'avoir une messagerie instantanée en complément.

5. Retour d'expérience

Git et Github : ce n'est pas suffisant

• Il faut de la communication 💬.
• Il est important d'avoir un outil de communication collaboratif en parallèle du dépôt Github : (Tchap dans le cas d'utilitR) ;
• Cet outil permet de se coordonner et de faire circuler l'information :
  • publication nouvelle fiche ;
  • besoin relecteur ou rédacteur ;
  • debug ;
  • blagues...

5. Retour d'expérience

Avantages

• Traçabilité élevée des modifications ;
• Simplicité de mise à jour des outputs ;
• Ouverture des codes ;
• Collaboration renforcée ;
• Fiabilité du processus de publication ;
• Projet plus pérenne.

Défis

• Capacité à se coordonner et à s'écouter ;
• Nécessité de hiérarchiser les objectifs ;
• Il faut apprendre à maîtriser les outils ;
• Il faut trouver du temps pour contribuer ;
• Importance d'avoir quelques contributeurs expérimentés.

5. Retour d'expérience

Une "petite" bourde lors de la transition de Gitlab à Github (décembre 2020)

• Transition vers Github pour donner plus de visibilité que sur Gitlab

• Volonté de ne pas perdre l'historique du dépôt (commits, issues, pull request)

  • Utilisation d'un outil (node-gitlab-2-github) pour récupérer issues et pull request

• Problème: oubli désactivation notification mail

• Résultat: Olivier a reçu 2700 mails 😅

5. Retour d'expérience

Les coordinateurs du projet

5. Retour d'expérience

Le projet aujourd'hui et demain

• Un portail d'accès sous forme de site web :

  • La documentation principale est disponible sur www.book.utilitr.org ;
  • Guide des bonnes pratiques en R disponible sur www.pratiques.utilitr.org.

• Un point d'entrée : https://www.utilitr.org ;

• Un mail de contact : utilitr-contact@insee.fr.

• Besoin de nouveaux contributeurs pour aller plus loin:

  • Ajouter de nouveaux contenus ;
  • Mettre à jour certains contenus ;

  • Après utilitR , utilython ?

    • Lino est fou 😨 !

utilitR est une documentation vivante qui a besoin de vous !

Remerciements

Merci !