Il est possible de contribuer au projet utilitR de différentes manières, détaillées dans ce document. Les contributions peuvent prendre différentes formes, d'un avis argumenté suite à une relecture à des propositions de modification en passant par des propositions d'intégrations de nouveaux éléments dans le livre ou le site.
Tip
Il n'est pas nécessaire d'être un expert en R pour contribuer au projet utilitR. En revanche, il est nécessaire de s'inscrire dans le fonctionnement
des contributeurs actuels, fonctionnement qui est orchestré autour de Github et de ses différents outils.
Il est possible d'en acquérir très rapidement les bases à partir de cette formation ou à partir d'échanges avec les contributeurs actuels.
Un environnement prêt à l'emploi pour l'exécution des scripts est disponible sur le SSPCloud. Il est présenté dans une section dédiée.
Pour ce type de modifications, il est demandé d'utiliser directement l'outil de suggestions de changements de Github. Le livre déployé sur https://book.utilitr.org comprend un bouton Edit qui permet de proposer, automatiquement, des modifications via l'interface de Github.
L'équipe du projet utilitR dispose d'un espace de discussion collective sur les problèmes techniques et les développements futurs du projet. Cet espace de discussion est stocké sur le dépôt Github du projet et est structuré sous forme d'issues.
Une issue est un fil de discussion permettant aux contributeurs du projet (mais aussi aux personnes extérieures) d'échanger sur un sujet précis (défini par le titre de l'issue). Vous pouvez consulter la liste des issues ouvertes en suivant ce lien.
Un relecteur peut proposer de relire une ou plusieurs fiches de son choix, ou suivre les indications des contributeurs du projet.
Warning
Attention: relire une fiche ne consiste pas à la remanier intégralement. La relecture doit porter sur les éléments suivants: clarté de l'exposé, cohérence de l'organisation des paragraphes, correction de l'expression, pertinence des conseils, reproductibilité des exemples. Autrement dit, le relecteur a pour rôle de vérifier que la fiche est compréhensible par un utilisateur standard. En revanche, la relecture ne porte pas sur les recommandations formulées dans la fiche, ni sur son organisation globale.
Le lieu idéal de retour de la part d'un relecteur ou d'une relectrice dépend du type de modification envisagée :
- Proposer des corrections mineures (faute d'orthographes, formulations peu claires) : il est recommandé de passer directement par l'interface de Github ;
- Pour des problèmes plus importants, il est possible d'ouvrir une issue
Caution
Ajouter une nouvelle fiche thématique à la documentation représente un travail conséquent qui requiert l'approbation de la majorité des contributeurs du projet.
La première étape consiste à ouvrir une issue dans le
dépôt Github.
Une fois que l'équipe de contributeurs est d'accord sur l'objet de la fiche et les grandes lignes de son contenu, la fiche peut être rédigée en suivant la procédure décrite ci-dessous.
Caution
Ne pas travailler sur la branche main de son fork. Celle-ci servira à mettre à jour le fork pour intégrer les dernières mises à jour de la documentation utilitR.
Plutôt que d'utiliser un environnement en local dont la configuration peut différer de manière parfois significative avec l'environnement canonique qui sert à générer la documentation utilitR sous Github, il est recommandé d'utiliser le service RStudio du SSPCloud.
Pour contribuer à utilitR, il est possible de créer un service RStudio entièrement paramétré, de la manière suivante. Voici, en résumé, avant quelques détails, le principe général:
- Mettre de côté l'URL de votre fork du projet
utilitR(celui terminant par.git) - Copier-coller le lien préconfiguré pour ouvrir l'interface de configuration de votre service
- Dans l'onglet
Git, coller l'URL de votre dépôtGithub - Lancer la création du service, attendre puis ouvrir lorsque celui-ci est prêt. Vous devriez avoir un RStudio prêt à l'emploi.
- Faire des modifications et tester le bon fonctionnement en prévisualisant le résultat
- Soumettre ces modifications par une pull request après les avoir poussées sur Github.
Note
S'il est nécessaire d'utiliser un nouveau package R, par exemple toto, il faut l'installer via la commande rv add toto en ligne de commande
Seuls les mainteneurs du dépôt utilitR ont les droits d'écriture sur le dépôt officiel de la documentation. Pour pouvoir proposer de nouvelles fiches, il faut passer par un dépôt intermédiaire sur lequel vous avez les droits d'écritures: un fork.
Un service préconfiguré presque prêt à l'emploi est disponible en cliquant sur ce lien
https://datalab.sspcloud.fr/launcher/ide/rstudio?name=rstudio%20utilitr&version=2.4.6&s3=default&init.personalInit=%C2%ABhttps%3A%2F%2Fraw.githubusercontent.com%2FInseeFrLab%2FutilitR%2Frefs%2Fheads%2Fmain%2Finit_utilitr.sh%C2%BB&kubernetes.role=%C2%ABadmin%C2%BB&git.repository=%C2%ABhttps%3A%2F%2Fgithub.com%2Finseefrlab%2Futilitr.git%C2%BB&networking.user.enabled=true&autoLaunch=false
Ne pas lancer tout de suite. Dans l'onglet Git, il faut remplacer l'URL d'utilitr par celui de votre dépôt. Après avoir fait cela, vous pouvez lancer.
Il est recommandé d'effectuer ses modifications depuis une branche différente de main.
La liste des fiches à tester est gérée par le fichier _quarto.yml. Vous pouvez la mettre à jour pour voir la mise en forme de vos modifications. L'idée n'est pas de mettre toutes les fiches dans ce fichier, sinon la compilation est assez longue, mais plutôt celles sur lesquels on désire faire des modifications.
Il est recommandé de lancer régulièrement des compilations de la documentation pour prévisualiser les résultats. Deux manières de faire:
- Via le bouton RStudio
Render - En passant par la ligne de commande en lançant
quarto preview --port 5000 --host 0.0.0.0.
Pendant ce temps, vous pouvez commencer à tester vos modifications: la prévisualisation se rafraîchira régulièrement.
Si vous devez ajouter des packages, par exemple toto, il faut taper la commande rv add toto.