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 connecter sur Github, nous nous trouvons sur une page qui nous montre notre activité sur ce réseau. A droite de la page, nous pouvons observer les derniers dépôts (On parle de Repositories dans GitHub) sur lesquels vous avez travaillé et au centre votre activité récente.

Nous pouvons également visiter notre profil. A droite, il y a une photo et une petite présentation vous concernant tout comme vous le retrouvez sur tout réseau social, au centre vos projets récents (Popular repositories) et vos contributions générale sur ce réseau social. Les contributions sur le réseau est très important. Il indique de manière globale votre travail ou plutôt votre apport sur vos différents projets.

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

B.2.2 Vos projets

Sur GitHub, vous pouvez héberger vos projets (qui se nomment sur GitHub repositories). Notre exemple se base sur le projet sdd-umons-2021, que vous pouvez librement consulter. 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 le point central de GitHub. Un dépôt public peut être vu par tous. Il peuvent y apporter des modifications et puis vous soumettre les modifications. Nous reviendrons plus tard sur ces apports par la communauté. Pour des projets plus sensibles, vous avez la possibilité d’avoir des projets privés.

Un dépôt sur GitHub est proposé de la manière suivante. Vous pouvez observer le nom du dépôt et la personne ou l’organisation qui travaille sur ce projet (BioDataScience-Course/sdd-umons-2021). Dans notre cas, tous les projets relatifs au cours de sciences des données biologiques sont hébergés sur BioDataScience-Course (Il en sera de même pour tous les travaux que vous réaliserez dans le cadre des cours). Sous le nom du dépôt, vous pouvez observer, le dépôts sur lequel ce projet s’inspire (phgrosjean/bookdown-test).

Vous pouvez observer une première barre d’outils comprenant les sections Code, Issues, Pull requests, Projects, 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 observer une nouvelle barre d’outils qui comprend les sections suivantes : commits, branches, releases, environment, contributors et View license.

Nous pouvons observer pas moins de 270 commits (Rappelez vous qu’un état d’avancement d’un projet est un commit).

B.2.2.2 Issues

Cette section est prévue afin de discuter, de réfléchir et de collaborer sur un projet commun.

B.2.2.3 Insights

La section Insights nous renseigne sur l’activité de notre projet. On peut y voir par exemple les contributeurs (Contributors) du projet. Nous avons donc quatre personnes qui ont contribué à cet ouvrage.

Les informations fournies dans cette section sont employées dans le cadre des corrections des travaux de groupes.

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

Lorsque nous souhaitons créer un nouveau projet sur 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 un responsable.

  • Repository name

Nous devons définir un nom pertinent pour notre projet.

  • Description

Nous pouvons proposer 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 le README. Ce dernier est un fichier qui 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.

  • .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 avec des langages très variés.

  • license

Nous pouvons adjoindre à notre projet une licence. Il en existe plusieurs afin d’expliquer 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 à définir votre licence.

Une fois votre dépôt configuré, il ne vous reste plus qu’à le cloner comme expliqué dans la section B.2.4.

B.2.4 Cloner un dépôt existant

Lorsque nous souhaitons travailler sur un de nos projets, il faut commencer par le cloner pour avoir une copie en local de ce dernier.

B.2.4.1 Via RStudio

Pour commencer, vous devez copier le lien menant à votre dépôt sur GitHub. Il vous suffit de cliquer sur le bouton vert Codeet de copier l’URL proposée (vous avez d’ailleurs un bouton en forme de presse-papier à cet effet).

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 (Laissez le nom par défaut est une bonne pratique), choisir un dossier pour cloner votre dépôt (le sous-dossier projects, du dossier shared est dédié à cela) et créer une copie en local de votre projet en cliquant sur Create Project. Vous êtes enfin prêt à éditer votre projet. N’oubliez pas de réaliser des Commit, des Pull et des Push.

B.2.4.2 Via GitHub Desktop

Github Desktop est un programme mis au point afin de faciliter l’utilisation de GitHub. Cloner un dépôt avec GitHub Desktop est d’une simplicité déconcertante.

Depuis Github, cliquez sur le bouton vert Code puis Open with GitHub Desktop et enfin acceptez l’ouverture de Github Deskop.

Dans GitHub Desktop, une fenêtre de configuration s’ouvre, il suffit de sélectionner le dossier où l’on souhaite placer le dépôt.

Cette fonction n’est disponible que sur la version Mac et Windows de GitHub Desktop

B.2.5 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 Commit), nous souhaitons le partager sur GitHub. Rassurez-vous, il ne faut pas tout recommencer. Il aurait cependant été plus simple de réfléchir dès le début du projet à cette éventualité, mais cela reste parfaitement faisable à ce stade.

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.

B.2.5.1 Via RStudio

Nous partons d’un projet RStudio d’exemple qui se nomme repos-example. Comme vous pouvez le voir, ce projet comprend trois Commit mais nous ne pouvons ni faire des Pull et des Push. C’est tout à fait normal puisque notre projet n’existe pas sur GitHub.

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.3. 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 Git local.

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 sur GitHub, vous pouvez recharger votre page dans https://github.com.

B.2.5.2 Via GitHub Desktop

Nous partons d’un projet RStudio d’exemple qui se nomme repos-example2 similaire au projet présenté précédemment.

Dans GitHub Desktop, vous devez sélectionner le menu File, puis Add Local Repository.... Vous devez commencer par sélectionner le dossier de votre projet, puis de publier votre dépôt (publish repository). C’est à nouveau un programme très simple d’utilisation.

B.2.6 Copier un dépôt

Lorsque vous souhaitez apporter votre aide sur 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 requests. 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. Ce dernier pourra accepter ou refuser vos modifications.

B.2.7 Personal Access Token

L’authentification sur GitHub requiert l’utilisation d’un Personal Access Token (PAT). 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 ou Renku), entrez la commande suivante dans votre console et tapez sur 
usethis::create_github_token()

Vous êtes automatiquement redirigé vers GitHub dans votre browser 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.

2. Modifiez la date d’expiration de ce dernier

Vous pouvez conserver tout cela tel quel. Cependant, votre clé d’authentification (token) a un durée limitée de validité par défaut de 30 jours. Dans le champ Expiration, nous vous conseillons de changer cette 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). La valeur de votre token est affichée dans un encadré en vert avec une petite icône de presse-papier à sa droite. Cliquez sur cette icône presse-papier pour copier la valeur de votre token. 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).

4. Revenez dans RStudio dans l’onglet Console. Comme indiqué dans les instructions, exécutez maintenant la commande suivante (puis ):

gitcreds::gitcreds_set()
  1. 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. La chaîne de caractère correspondante de votre token est collée dans la Console. Tapez ensuite sur la touche .

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

Une fois cela réalisé, vous pourrez de nouveau faire vos push et pull dans GitHub…