-
Notifications
You must be signed in to change notification settings - Fork 4
/
Copy pathcolaboratif.Rmd
534 lines (381 loc) · 20.2 KB
/
colaboratif.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
---
title : "__`utilitR`__"
subtitle : "Présentation de la démarche collaborative `utilitR`"
author : "Lino Galiana"
date : "9 juin 2021"
output:
xaringan::moon_reader:
new_session: yes
self_contained: false
css:
- css/default.css
- css/default-fonts.css
- css/style-utilitr.css
- css/icones-fa.css
- css/metropolis.css
- css/customize-slides.css
- css/custom.css
includes:
after_body: insert-logo.html
lib_dir: libs
nature:
highlightStyle: github
highlightLines: true
countIncrementalSlides: false
---
# Introduction
```{r setup, include=FALSE}
options(htmltools.dir.version = FALSE)
```
.sauterligne3[
Le projet `utilitR` vise à produire une documentation collaborative sur `R`,
destinée principalement aux agents du Service statistique public (mais pas exclusivement).
]
--
.sauterligne2[
Plan de la présentation :
]
- 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 ;
<!----
+ Git & Github
+ CI/CD
----->
---
# 1. Présentation du projet
## Une démarche collaborative et _open source_
* Projet entièrement _open source_ (`r fontawesome::fa("fab fa-github")` [`InseeFrLab`](https://github.com/InseeFrLab/utilitR)) :
+ 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 ! `r emo::ji("applause")`
--
* Organisation horizontale, sur le modèle de `Wikipedia` :
+ relecture par les pairs ;
+ validation collégiale ;
+ discussions publiques, toutes contributions bienvenues.
<br> __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](https://www.insee.fr) (grâce au _package_ [`doremifasol`](https://github.com/InseeFrLab/DoReMIFaSol)) ;
+ Documentation entièrement reproductible
[](https://datalab.sspcloud.fr/launcher/inseefrlab-helm-charts-datascience/rstudio?onyxia.friendlyName=%C2%ABrstudio-utilitr%C2%BB&init.personnalInit=%C2%ABhttps%3A%2F%2Fraw.githubusercontent.com%2FInseeFrLab%2FutilitR%2Fmaster%2Fresources%2Finit_9juin.sh%C2%BB&r.version=%C2%ABinseefrlab%2Futilitr%3A0.7.0%C2%BB)
+ Insee: exemples mobilisables dans AUS.
* Processus de publication à l'état de l'art :
+ Plusieurs _outputs_ (site web `r fontawesome::fa("fab fa-firefox")`, livre PDF `r fontawesome::fa("fas fa-file-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 `r fontawesome::fa("fab fa-r-project")` :
+ `Docker` `r fontawesome::fa("fab fa-docker")` ;
+ `Git` `r fontawesome::fa("fab fa-git-alt")` ;
+ `Github` `r fontawesome::fa("fab fa-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.
<br>
__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
```{r, echo = FALSE}
knitr::include_graphics("https://i2.wp.com/akramsideas.com/wp-content/uploads/2013/07/minions.jpg")
```
__Rejoignez l'aventure `utilitR` !__
---
# 1. Présentation du projet
## Diffusion de la documentation
La documentation est diffusée sous trois formes :
- `r fontawesome::fa("fab fa-firefox")` un site internet ([www.utilitr.org](https://www.utilitr.org)) ;
- `r fontawesome::fa("fas fa-print")` chaque fiche est disponible en format A4 sur le site internet ;
- `r fontawesome::fa("fas fa-file-pdf")` l'intégralité de la documentation en format pdf.
<br> 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).
<br> `utilitR` est en évolution constante, venez proposer vos idées ou donner un coup de main !
<!---- PARTIE 2 ---------------->
---
# 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](https://github.com/InseeFrLab/utilitR/blob/master/Manifeste.md) : transparence, ouverture, bienveillance, exigence et reproductibilité.
--
* Organisation sans hiérarchie :
* Un _groupe de contributeurs_ `r emo::ji("black_nib")` (environ 25), parmi lesquels deux coordinateurs ;
* Un _comité de parrainage_ composé de managers `r emo::ji("angel")`: 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](https://github.com/InseeFrLab/utilitR/blob/master/CONTRIBUTING.md).
--
<br><br>
**Vous pouvez rejoindre l'équipe de contributeurs à tout moment.**
---
# 2. Fonctionnement du projet
## Organisation du projet
<table class = "tablelol">
<tr>
<td style = "width: 35%;">Le comité de parrainage</td>
<!-- <td><img src="https://imperialtalker.files.wordpress.com/2015/08/the-council.jpeg" alt="2" style = "width: 75%;" class = "lol"></td> -->
<td>
<div class="row">
<div class="column">
<img src="https://images-na.ssl-images-amazon.com/images/I/71MA6epP0WL._AC_SL1500_.jpg" alt="Snow" style="width:100%">
</div>
<div class="column">
<img src="https://media.vogue.fr/photos/606dca7e47f477da2ff11fcf/2:3/w_2560%2Cc_limit/010_A7A08C89_416.jpg" alt="Forest" style="width:100%">
</div>
<div class="column">
<img src="https://upload.wikimedia.org/wikipedia/en/1/1b/Princess_Leia%27s_characteristic_hairstyle.jpg" alt="Mountains" style="width:100%">
</div>
</div>
</td>
</tr>
<tr>
<td>Les contributeurs</td>
<td> <img src="https://lumiere-a.akamaihd.net/v1/images/databank_ewok_01_169_747db03a.jpeg?region=0%2C0%2C1560%2C878&width=768" alt="1" style = "width: 90%;" class = "lol" ></td>
</tr>
</table>
---
# 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](https://github.com/InseeFrLab/utilitR/blob/master/Manifeste.md)
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](https://www.github.com/inseefrlab/utilitr).
```{r, echo = FALSE, out.width="85%", fig.align="center"}
knitr::include_graphics("./resources/graphCI/githubCI_1.png")
```
---
# 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.
```{r, echo = FALSE, out.width="85%", fig.align="center"}
knitr::include_graphics("./resources/graphCI/githubCI_2.png")
```
---
# 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.
```{r, echo = FALSE, out.width="85%", fig.align="center"}
knitr::include_graphics("./resources/graphCI/githubCI_3.png")
```
---
# 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](https://www.book.utilitr.org).
```{r, echo = FALSE, out.width="85%", fig.align="center"}
knitr::include_graphics("./resources/graphCI/githubCI_complete.png")
```
---
# 2. Fonctionnement du projet
## Une approche au service de la reproductibilité et de la qualité
C'est le dépôt [`Github` `r fontawesome::fa("fab fa-github")` d'`utilitR`](https://github.com/InseeFrLab/utilitR) qui centralise tout le fonctionnement du projet. Il propose :
* Un __environnement informatique complet et reproductible__ pour produire la documentation (image `Docker` `r fontawesome::fa("fab fa-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** `r fontawesome::fa("fab fa-firefox")` (via `Netlify`) sur lequel les contributeurs peuvent voir les modifications qu'ils apportent au site, sans que le site public ne soit modifié.
[](https://hub.docker.com/repository/docker/inseefrlab/utilitr/general)
[](https://github.com/InseeFrLab/utilitR/actions)
---
# 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* `r fontawesome::fa("fab fa-github")` sur [www.book.utilitr.org](https://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.
--
.sauterligne2[
Deux points à retenir :
]
- __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
<br><br><br><br>
**[Démonstration !](https://github.com/InseeFrLab/utilitR-website)**
---
# 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](https://github.com/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.
```{r, echo = FALSE}
knitr::include_graphics("resources/git-tree.png")
```
<br> __Ce mode de travail est exportable à un environnement interne `Gitlab` `r fontawesome::fa("fab fa-gitlab")`__
---
# 4. Intégration continue
## Avantages de l'automatisation des processus :
```{r, eval = FALSE, echo = FALSE, out.width="50%", fig.show="hold"}
knitr::include_graphics("https://crowdspotsimages.s3-us-west-2.amazonaws.com/user-content/LcYPp_4UQjuu44T_RXp8qg.jpeg")
knitr::include_graphics("https://flexagon.com/wp-content/uploads/2020/04/a-world-without-ci.cd-meme.jpg")
```
<!---
Sources :
`https://crowdspotsimages.s3-us-west-2.amazonaws.com/user-content/LcYPp_4UQjuu44T_RXp8qg.jpeg`
`https://flexagon.com/wp-content/uploads/2020/04/a-world-without-ci.cd-meme.jpg`
---->
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**.
```{r, echo = FALSE, out.width="50%", fig.show="hold", fig.align='center'}
knitr::include_graphics("https://flexagon.com/wp-content/uploads/2020/04/a-world-without-ci.cd-meme.jpg")
```
---
# 4. Intégration continue
## `R Markdown`, *un langage pour les gouverner tous*
<!-- en un site web ou un PDF cohérent (gestion des numéros de chapitre, des -->
<!-- liens entre fiches, etc.) -->
<!-- (`.Rmd` ➜ `.md` ➜ `.html`) ; -->
<!-- (`.md` ➜ `.html` ➜ `.pdf`) ; -->
* 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_.
--
<br>
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 `r fontawesome::fa("fab fa-git-alt")` et Github `r fontawesome::fa("fab fa-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* `r fontawesome::fa("fab fa-github")` sur le site)
+ Intérêt d'avoir une messagerie instantanée `r fontawesome::fa("fas fa-comment")` en complément.
---
# 5. Retour d'expérience
## Git `r fontawesome::fa("fab fa-git-alt")` et Github `r fontawesome::fa("fab fa-github")`: **ce n'est pas suffisant**
* Il faut de la **communication** `r emo::ji("comment")`.
* 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 `r fontawesome::fa("fab fa-github")`](https://github.com/InseeFrLab/utilitR) pour donner plus de visibilité que sur Gitlab `r fontawesome::fa("fab fa-gitlab")`
* Volonté de ne pas perdre l'historique du dépôt (commits, issues, pull request)
+ Utilisation d'un outil ([node-gitlab-2-github](https://github.com/piceaTech/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 `r emo::ji("sweat_smile")`
```{r, echo = FALSE, out.width="50%", fig.show="hold"}
knitr::include_graphics("resources/Spamomatic.jpg")
knitr::include_graphics("resources/Spamomatic2.jpg")
```
---
# 5. Retour d'expérience
## Les coordinateurs du projet
```{r, echo = FALSE, out.width="45%", fig.align='center'}
knitr::include_graphics("https://images-na.ssl-images-amazon.com/images/I/91CJLS0pRJL.jpg")
```
---
# 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](www.book.utilitr.org) ;
+ Guide des bonnes pratiques en `R` disponible sur [www.pratiques.utilitr.org](www.pratiques.utilitr.org).
* Un point d'entrée : <https://www.utilitr.org> ;
* Un mail de contact : [email protected].
--
<br>
* Besoin de nouveaux contributeurs pour aller plus loin:
+ Ajouter de nouveaux contenus ;
+ Mettre à jour certains contenus ;
+ Après `utilitR` `r fontawesome::fa("fab fa-r-project")`, `utilython` `r fontawesome::fa("fab fa-python")` ?
--
+ Lino est fou `r emo::ji("fear")` !
--
<br>
__`utilitR` est une documentation vivante qui a besoin de vous !__
---
# Remerciements
<!-- Le projet `utilitR` est un projet collaboratif qui a bénéficié des contributions de : -->
<!-- r paste0(paste(format(Filter(function(x) !("cph" %in% x$role), desc::desc_get_authors()), include = c("given", "family")), collapse = ", "), ".") -->
.small90[
.auteurs[
Contributeurs : Raphaële Adjerad, Mathias André, Pierre-Yves Berrard, Lionel Cacheux, Arthur Cazaubiel, Frédérique Cornuau, Sylvain Daubrée, Aurélien d'Isanto, Arlindo Dos Santos, Alexis Eidelman, Marie-Emmanuelle Faure, Gilles Fidani, Lino Galiana, Gaëlle Genin, Pierre Lamarche, Claire Legroux, Romain Lesur, Jean-Daniel Lomenède, Pascal Mercier, Olivier Meslin, Violaine Poirot, Géraldine Rochambeau, Clément Rousset, Milena Suarez Castillo, Cédric Tassart.
Coordination : Pierre-Yves Berrard, Lino Galiana et Olivier Meslin.
Comité de parrainage : Arnaud Degorre, Benoît Rouppert, Patrick Sillard et Sébastien Roux.
Logo : Anna Schlaifer.
Les contributeurs remercient Julien Taquet et Marc Hufschmitt pour leur aide précieuse sur la mise en forme du site et de la brochure.
]
]
---
background-image: url('resources/logo-utilitr.png')
background-size: 7cm
background-position: 8.5cm 3cm
# Merci !