B.2 GitHub

Un réseau social a été conçu autour de Git pour sauvegarder vos projets sur le “cloud”, les partager et collaborer avec d’autres personnes. Ce système se nomme GitHub (tout comme Facebook ou LinkedIn). GitHub rassemble donc “Git”, la gestion de version et “Hub” relatif au réseau. D’autres réseaux équivalents existent comme Gitlab ou Bitbucket.

B.2.1 Votre activité et profil

Pour vous montrer différentes sections sur GitHub, nous utiliserons le compte de GuyliannEngels. Une fois connecté sur Github, nous nous trouvons sur une page qui nous montre notre activité sur ce réseau. En bas de la page, nous pouvons observer les dépôts épinglés (section “Pinned”) que vous considérez comme les plus importants.

Plus bas dans la page, il y a un graphique qui représente vos contributions au cours du temps. Il indique de manière globale votre travail, c’est-à-dire vo contributions dans les différents projets.

Dans notre exemple, nous pouvons observer 983 contributions sur l’année écoulée.

B.2.2 Vos projets

GitHub vous sert à héberger vos projets (qui se nomment des repositories). Notre exemple se base sur le projet sdd-umons-2022, que vous pouvez librement consulter et qui contient les sources du présent ouvrage en ligne. Il s’agit en effet d’un dépôt public. Vous avez la possibilité d’avoir des projets publics ou privés.

Les projets publics sont visibles par tous. La collaboration est la pierre angulaire de GitHub. Donc, tout le monde peut y apporter des modifications dans des copies de vos dépôts et puis vous les proposer d’une manière qui vous permet d’examiner les améliorations suggérées, de les discuter, et enfin de les incorporer ou de le rejeter. Cela s’appelle un Pull request, mais nous y reviendrons plus tard. Pour des projets plus sensibles, vous avez la possibilité d’avoir des projets privés.

La référence à un dépôt sur GitHub est composée de deux éléments. Le premier est le nom de la personne ou de l’organisation auquel le dépôt appartient. Le second élément est le nom du dépôt lui-même. la personne ou l’organisation qui travaille sur ce projet. Dans notre exemple, nous aurons donc BioDataScience-Course/sdd-umons-2022. Tous les projets relatifs au cours de sciences des données biologiques à l’UMONS sont hébergés dans l’organisation BioDataScience-Course (Il en sera de même pour tous les travaux que vous réaliserez dans le cadre de vos cours).

Vous pouvez observer une première barre d’outils comprenant les sections Code, Issues, Pull requests, Projects, Actions, Projects, Wiki, Security, Insights et Settings (toutes les sections ne seront pas détaillées dans cet ouvrage).

B.2.2.1 Code

Dans cette section, vous pouvez visualiser le contenu des différents fichiers qui se trouvent dans le dépôt. Vous naviguez dans les sous-dossiers simplement en cliquant dessus. La visualisation des fichiers propose éventuellement plusieurs présentations dont le mode “Raw” pour voir le texte brut. C’est l’équivalent du mode “Source” dans l’éditeur de documents R Markdown de RStudio. Le bouton vert Code dans cette section est important. C’est grâce à lui que vous pourrez récupérer le contenu du dépôt. On parle de cloner un dépôt.

Comme il s’agit d’un système de gestion de versions, toutes les versions successives du dépôts sont stockées et accessibles, mais au départ, vous ne voyer que la dernière version. Chaque fois que vous enregistrez une version, vous réaliser un commit. Le nombre de commits et des informations à son propos sont présentées dans la barre grisée sous les quelques boutons.

B.2.2.2 Issues

Cette section est prévue pour discuter des problèmes ou des idées à développer. C’est une sorte de petit forum de discussion. Vous utiliserez ces “issues” pour poser vos questions à vos enseignants et pour interagir entre vous dans les projets de groupe.

B.2.2.3 Insights

La section Insights nous renseigne sur l’activité du projet. On peut y voir par exemple les contributeurs du projet, le nombre de commits réalisés par chacun, etc.

Concernant vos projets dans le cadre du cours, ces informations sont employées pour évaluer la contribution de chacun dans les travaux de groupes et ajuster la note en fonction.

B.2.3 Permettre à RStudio de communiquer avec GitHub

Dans le cours de Science des Données vous utiliserez RStudio pour éditer vos documents et travailler avec R. Mais d’autre part, vous partagerez vos œuvres via GitHub. C’est d’ailleurs un schéma classique que nous vous conseillons d’adopter aussi en dehors du cours ! Les professionnels travaillent tous comme cela. Nous devons donc trouver un moyen de permettre à RStudio de communiquer avec GitHub. Les fonctionnalités existent, dans l’onglet Git (qui n’apparait que si vous êtes dans un projet géré par git). Encore faut-il indiquer à GitHub que vous autoriser votre RStudio à accéder à votre compte et à vos dépôts. Pour cela, deux solution très différentes existent : le code d’accès personnel PAT, un code généré par GitHub et que vous incluez dans votre SciViews Box, ou la clé SSH, une clé privée/publique générée au contraire dans votre logiciel et dont vous renseignez la partie publique à GitHub pour qu’il puisse l’utiliser. Nous allons voir ces deux méthodes successivement, sachant que la version locale de la SciViews Box utilise le PAT, alors que c’est plus facile d’utiliser la clé SSH dans Saturn Cloud.

B.2.3.1 Personal Access Token

L’authentification dans GitHub peut se faire via un Personal Access Token (PAT). Il s’agit d’une sorte de mot de passe long et compliqué (donc bien sécurisé) que GitHub génère pour vous et que vous devez renseigner à tout logiciel souhaitant accéder à votre compte. Ce système d’authentification ne doit être réalisé qu’une seule fois dans RStudio. La procédure est la suivante.

  1. Dans RStudio (que vous aurez lancé au préalable via la machine virtuelle en local), entrez la commande suivante dans votre console et appuyez sur <enter>.

    usethis::create_github_token()

Vous êtes automatiquement redirigé vers GitHub dans votre navigateur Web (il faut peut-être s’y identifier). Vous êtes face à une page qui s’appelle “New personal access token”. Les champs sont déjà préremplis.

  1. Modifiez la date d’expiration

Vous pouvez conserver les options telles quelles. Cependant, votre clé d’authentification a une durée de validité limitée à 30 jours par défaut. C’est une bonne pratique de renouveler ses mots de passe régulièrement, mais chaque mois… c’est un peu court. Dans le champ Expiration, nous vous conseillons de changer la valeur pour couvrir toute votre année académique.

  1. Générez votre “token” en cliquant sur le bouton vert “Generate token” tout en bas de la page.

Vous vous retrouver à présent dans une nouvelle page GitHub qui liste tous vos PATs (vous n’en aurez probablement qu’un seul à ce stade). Votre token est affiché dans un encadré en vert avec une petite icône de presse-papier à sa droite. Cliquez sur cette icône presse-papier pour le copier. Attention : une fois sorti de la page, vous ne pourrez plus jamais voir ce token (mais vous pourrez en recréer d’autres si nécessaire, pas de panique).

À ce propos, n’enregistrer pas ce token sur votre ordinateur, tout comme d’ailleurs n’importe quel mot de passe, à moins d’utiliser un logiciel coffre-fort comme Keeweb, mais ici ce n’est pas nécessaire. Aucun de vos mots de passe ne doit se trouver dans vos notes, vos fichiers Word ou Excel, votre messagerie, etc. ni dans votre ordinateur, ni dans votre smartphone. C’est une faute grave et une brèche de sécurité énorme que vous offrez aux hackers mal intentionnés que de stocker en clair vos mots de passe sous forme électronique.

  1. Revenez dans RStudio dans l’onglet Console. Comme indiqué dans les instructions, exécutez maintenant la commande suivante (puis appuyez sur <enter>):

    gitcreds::gitcreds_set()

  2. Vous avez un message qui vous demande votre token. Collez-le dans la Console à l’aide du raccourci <Ctrl+V> (ou <Command+V> sur le Mac) ou clic bouton droit dans la Console et sélection de l’entrée de menu contextuel Paste. Votre token est collé dans la Console. Validez ensuite avec la touche <enter>.

Votre token doit à présent être enregistré dans la SciViews Box.

Une fois cela réalisé, vous pourrez travailler dans GitHub depuis RStudio (clone de dépôts, push/pull, …). Si plus tard, vous perdez ce lien et que Rstudio se plaint de ne pas pouvoir communiquer avec GitHub et vous demande un mot de passe, vous devez alors régénérer un autre token et suivre la même procédure à nouveau.

B.2.3.2 Clé SSH dans Saturn Cloud

Le principe de la clé SSH est assez différent. Vous créez dans votre ordinateur une paire de clés. L’une est publique et sert à encoder les données à un bout de la chaîne. L’autre est privée et ne réside que sur votre ordinateur. Elle est nécessaire pour pouvoir décoder les données. Donc, avec la clé publique, on peut encoder mais pas décoder. La procédure de création des clés privée/publique est un rien plus compliquée que la génération du PAT. Mais Saturn Cloud nous propose de le faire pour nous, et en plus, de générer une seule paire de clés pour l’ensemble de nos ressources. C’est donc bien pratique. La procédure relative à la clé SSH entre SaturnCloud et GitHub est intégrée dans la page du site accessible depuis le bouton bleu RStudio en haut à droite. Cependant, au cas où vous devriez refaire l’opération, elle est brièvement rappelée ci-dessous.

Dans SatunCloud, vous vous identifiez dans votre compte. Ensuite, vous cliquez sur USER et choisissez Manage . Là, vous avez une page nommée Access Keys. C’est la boite du milieu indiquée Git SSH Key qui nous intéresse. Vous allez créer cette clé (en demandant à SaturnCloud de le faire pour vous). Ensuite, vous verrez une boite de dialogue qui expose la clé publique ainsi générée. Cliquez sur l’icône en forme de presse-papier pour la copier.

Rendez-vous dans un second temps sur GitHub.com où vous vous identifiez et vous allez dans les paramètres de votre compte. Pour cela, vous cliquez sur votre avatar en haut à droite de la page du site et vous sélectionnez Settings dans le menu déroulant. Vous allez dans la section SSH and GPG keys à gauche, puis dans SSH keys vous cliquez sur le bouton New SSH key. Vous indiquez un titre qui ne soit pas déjà utilisé si vous avez déjà d’autres clés enregistrées (nous vous conseillons SaturnCloud). Enfin, vous collez la clé publique depuis le presse-papier dans le champ Key. Vous terminer l’opération en cliquant sur le bouton Add SSH key. En principe, la communication entre RStudio et GitHub est effective à présent. Cette clé n’expire pas et ne doit pas être recréée. Mais si vous suspectez un problème, vous pouvez toujours en recréer un autre dans Saturn Cloud. Ensuite, dans GitHub vous effacez l’ancienne et ajouter la nouvelle de la même façon.

Que ce soit via un PAT ou via la clé SSH, RStudio ne doit vous demander aucun mot de passe et ne doit pas afficher de message d’erreur de connexion lors d’opérations de clonage de dépôt, de pulls et de pushes. Lorsque vous clonerez vos dépôts depuis GitHub, vous devrez par contre penser à utiliser la référence HTTPS si vous utilisez un PAT, et la référence SSH si vous utilisez une clé SSH. Si vous inversez les références, cela ne fonctionnera pas !

B.2.4 Créer un dépôt

Lorsque nous souhaitons créer un nouveau dépôt GitHub, nous devons l’initialiser comme suit :

Pour créer un nouveau dépôt (Create a new repository), nous devons fournir les informations suivantes :

  • Repository template

Nous devons décider d’utiliser ou non un “template” existant parmi la liste des templates que nous avons à disposition.

  • Owner

Nous devons décider du responsable du dépôt soit une organisation ou une personne.

  • Repository name

Nous devons choisir un nom court mais pertinent pour notre dépôt et qui ne soit pas déjà utilisé dans l’organisation ou l’espace de l’utilisateur sélectionné.

  • Description

Nous pouvons indiquer ici une courte description de notre dépôt.

  • Public ou Private

Nous devons décider si notre projet est public ou privé.

  • README

Nous pouvons éditer un fichier de présentation qui se nomme “README”. Ce dernier va présenter succinctement notre projet. On peut l’éditer depuis GitHub directement. Si ce fichier est au format Markdown (nettement conseillé), il se nommera alors README.md. Ainsi, vous pourrez formater les titres et le texte dans ce fichier.

  • .gitignore

Il est intéressant de configurer le dépôt avec un fichier .gitignore orienté sur l’utilisation de R. GitHub peut en effet héberger des projets dans des langages informatiques très variés.

  • license

Nous pouvons adjoindre à notre projet une licence. Il en existe plusieurs qui définissent précisément ce que l’on a le droit de faire ou non avec votre dépôt. Le site https://choosealicense.com peut vous aider à choisir la licence la plus appropriée en fonction du contenu que vous souhaitez y héberger. Une fois votre dépôt configuré, il ne vous reste plus qu’à le cloner comme expliqué dans la section B.2.5.

B.2.5 Cloner un dépôt existant via RStudio

Lorsque nous souhaitons travailler sur un de nos projets hébergé dans un dépôt GitHub, il faut commencer par le cloner pour avoir une copie en local de ce dernier. Notez que “local” signifie ici dans la machine sur laquelle nous travaillons. Si nous utilisons une ressource sur Saturn Cloud ou tout autre service sur le cloud comme RStudio Cloud, par exemple, le contenu du dépôt sera recopié dans la machine sur le cloud. Ce contenu sera donc “local” de manière relative au logiciel qui s’y exécute.

Pour commencer, vous devez copier le lien menant à votre dépôt GitHub. Il vous suffit de cliquer sur le bouton vert Code dans la section du même nom et de copier l’URL proposée dans le presse-papier (vous avez d’ailleurs un bouton avec une icone suggérant la copie pour le faire). Mais attention, avant de faire cela, il faut déterminer quel format doit être copié. Si vous vous identifiez via un PAT, il faut récupérer la version HTTPS. Si vous utilisez une clé SSH, vous devez utiliser la version SSH. Donc pour simplifier, si vous utiliser la SciViews Box en local choisissez HTTPS. Si au contraire, vous utilisez la SciViews Box dans Saturn Cloud, choisissez la version SSH.

Ensuite, vous devez vous rendre dans RStudio et cliquer sur Project en haut à droite, suivi de New Project... (Si les projets restent encore un peu flous pour vous, rendez vous dans la section @ref(#rs-projet)). Une nouvelle fenêtre s’ouvre. Vous devez sélectionner Version Control, puis Git dans les préférences successives.

Pour finir, vous devez :

  • renseigner l’URL précédemment copiée depuis GitHub,

  • choisir un nom à votre dépôt (une bonne pratique est de nommer votre projet du même nom que votre dépôt),

  • choisir un dossier pour cloner votre dépôt (le sous-dossier projects, du dossier shared est dédié à cela en version locale, ou le dossier workspace dans la version Saturn Cloud) et

  • créer une copie en local de votre projet en cliquant sur Create Project.

Vous êtes à présent prêt à éditer votre projet. Vous réaliserez des commit, des pull et des push pour enregistrer des versions successives de votre travail et pour les synchroniser avec le dépôt GitHub. Vous apprenez à faire cela dans le module 1 du cours.

B.2.6 Déposer un projet déjà créé

Nous avons créé un projet dans RStudio et l’avons configuré avec le gestionnaire de version git comme présenté dans l’annexe B.1.1.1. Cependant, après avoir progressé dans ce projet (et réalisé plusieurs commits), nous souhaitons le partager à présent via GitHub. Rassurez-vous, il ne faut pas tout recommencer. Il aurait été plus simple de réfléchir dès le début du projet à cette éventualité et de créer le dépôt GitHub en premier lieu, mais cela reste parfaitement faisable à ce stade de transformer un projet local RStudio en un dépôt GitHub.

Une bonne pratique avant de vous lancer dans un nouveau projet et de se poser et de réfléchir aux objectifs du projets et aux moyens à mettre en œuvre pour atteindre ces objectifs.

Nous partons d’un projet RStudio d’exemple qui se nomme repos-example. Comme vous pouvez le voir, ce projet comprend trois commits mais nous ne pouvons pas faire de pull ou push, puisque notre projet n’est pas lié à un dépôt distant.

Pour déposer un projet RStudio existant sur GitHub, vous devez commencer par créer un nouveau dépôt dans Github qui ressemble très fortement à l’annexe B.2.4. Avec une particularité que vous ne devez pas configurer le README, le .gitignore et la license. Comme le dépôt est vide, GitHub vous propose plusieurs options pour le remplir, dont …or push an existing repository from the command line . Il s’agit donc de mettre en ligne (push) un projet existant sous forme de dépôt local git.

Dans votre projet RStudio, sélectionnez le menu Tools puis Shell.... Un onglet Terminal vient de s’ouvrir à côte de l’onglet Console de R. Il vous suffit ensuite d’y copier les trois instructions proposée sur GitHub et de taper sur la touche entrée et le tour est joué.

Afin de vérifier que votre projet RStudio est correctement mis en ligne dans GitHub, vous pouvez recharger votre page dans https://github.com.

B.2.7 Copier un dépôt

Lorsque vous souhaitez apporter votre aide à un projet qui n’est pas le vôtre, vous devez réaliser un fork puis un clone. N’oubliez pas que la base de GitHub est de faciliter la collaboration. Afin de soumettre vos modifications au projet de départ, il faut faire un pull request. Cette étape permet de proposer vos modifications au responsable du projet original sous une forme qui lui permet de visualiser et de discuter les changements proposés. Il pourra alors, en connaissance de cause, accepter ou refuser vos modifications.