TP1 : Prise en main de l’environnement de travail

BUT 3 - Domaines d’application

Auteur

Jean-Francois Rey

Objectif du TP

Apprendre à utiliser Git - pour cela nous allons configurer un projet sous GitLab et l’associer à un projet sous Rstudio via Git.

Prérequis

Important

Créer vos binômes/trinômes de travail. Vous devez avoir un PC par membre, ou à défaut un navigateur par membre.

Choisir un nom de projet (nom du futur package R que nous allons créer)
> N’utilisez pas de caractères spéciaux, le nom doit commencer par une lettre.

Avertissement

Disposer des comptes Rstudio (sur https://guacamole.univ-avignon.fr/rstudio/) de chacun des membres du groupe projet.

Avertissement

Disposer des comptes sur GitLab de chacun des membres du groupe projet.

Pour vous connecter, utiliser vos comptes universitaire via le bouton “Fédération Education-Recherche”.

Rappel Git

Git est un outil libre et opensource de gestion de versions décentralisé créé en 2005 par Linus Torvalds.
Git sur wikipédia

Configurations

Avertissement

Chaque membre du projet doit réaliser sur son compte Rstudio et Gitlab la configuration.

Configurer Rstudio

Dans le cas où vous n’utilisez pas Rstudio comme IDE.
Votre IDE doit prendre en charge Git (natif, extension, plugin, etc…), sinon vous devrais utiliser un client Git ou le terminal en ligne de commande par la suite.

1- Vérifier que vous ne disposez pas déjà d’une pair de clé SSH dans votre /$HOME/.ssh/. (/$HOME <- répertoire courant utilisateur)
2- Si c’est le cas, générer la pair de clé dans le terminal (sous Windows vous pouvez utiliser PUTTY)

ssh-keygen -t rsa -b 4096 -C "email@univ-avignon.fr" -q -N ''  

4- Votre clé public ssh et dans le contenu du fichier avec l’extension .pub dans /$HOME/.shh par défaut)
3- Passer à l’étape de configuration de Git

Nous allons utiliser des clés ssh pour communiquer entre Rstudio et GitLab.

  • Dans le menu Tools -> Global Options : Menu svn/git

  • Si il n’y a pas de clé de spécifié cliquer sur Create SSH Key… sans mettre de mot de passe.

  • Vous devez avoir quelques choses comme ceci :

Astuce

En cliquant sur View public key vous avez accès à votre clé public qui peut être partagé (copier cette clé pour la coller plus tard).
Garder ceci en tête.

Vous pouvez constater que git est disponible /usr/bin/git dans le champ Git executable

Configuration de Git

Avertissement

Il se peut qu’il fasse configurer l’environnement git de votre session (chaque membre du projet sur sa session).
Pour ce faire, nous allons renseigner notre identifiant et email dans la console du terminal de Rstudio, comme ceci :

git config --global user.name "Prenom Nom"
git config --global user.email "Mon_id@univ-avignon.fr"

Pour vérifier que cela a fonctionné :

git config user.email

Vous devez voir votre email.

Configuration de GitLab

Pour communiquer entre Rstudio (git) et GitLab il faut renseigner la clé public ssh dans le settings de gitlab pour chaque compte.

Chaque membre du projet doit sur sa session GitLab :

  • Cliquer sur l’icône du compte (en haut à gauche) -> Edit Profile -> Menu de gauche SSH Keys
  • Ajouter une nouvelle clé (Add new key)

il suffit de copier-coller sa clé public fournie par Rstudio. Le Title peut être modifié comme bon vous semble.

Ceci permettra une communication entre Rstudio (git) et GitLab sans mot de passe.

Créer un projet

UN seul membre du projet (binôme) va effectuer/faire les étapes suivantes.

Mais les autres membres doivent comprendre ces étapes.

Si vous ne disposez pas d’un PC par membre vous pouvez utiliser un navigateurs par membres ou ouvrir des sessions privées dans le même navigateur pour chaque participants au projet.

Créer un projet sous GitLab

Un projet sous GitLab (dépôt) est une espace où votre code va être versionné grace à GIT et où vous avez accès à différents outils (wikis, permissions, issues, CI/CD, docker registry, etc.).

Note

GitLab est un outil web qui permet de gérer des projets versionné avec Git. (comme GitHub).
Plus spécifiquement, GitLab est un logiciel libre de forge basé sur Git qui propose pleins de fonctionnalités tel que la gestion de dépôt git (projet), les wikis, le suivie des bugs, la planification de projet, l’automatisation (intégration et la livraison continue CI/CD), etc.

Connectez vous à https://gitlab.paca.inrae.fr via votre navigateur web préféré.

  • UN membre du projet va créer un projet commun.
    • Depuis GitLab cliquer sur le bouton “New Project” et créer un projet vierge (blank project), en décochant initialize repository with a README)

    Pour le nom de votre projet choisir un nom pas trop long et qui sera le nom de votre futur package (éviter les noms génériques du genre package, notrepackage etc. ainsi que les caractères spéciaux). Le nom doit commencer par une lettre.
    Pas d’idée, nommer votre projet avec les initiales de vos NomPrénom (ex: Projet_jfr_jd)

    Note

    Dans la suite des TPs, le nom de votre projet (et package) sera identifier comme ceci : <monpackage>

    Dans le project URL selectionner votre namespace (votre identifiant, celui qui crée le projet). Le mien est “jfrey”. Vous pouvez utiliser aussi celui-ci du groupe cours/iut202X202X/ mais vos camarades aurront accès à votre projet.

  • Une fois créer vous êtes redirigé sur la page du projet. Il vous est proposé d’ajouter des nouveaux membres. Si ce n’est pas le cas aller dans menu de gauche : Manage -> Members -> Bouton “Invite Members”).
    Ajouter dans les membres du projet votre/vos camarade(s) du projet comme Owner ainsi que @jfrey (moi) avec le rôle Mainteneur (je suis déjà présent normalement).
C’est quoi les rôles

Les rôles c’est le niveau de droit sur le projet gitlab. Pour avoir plus d’information.

Création d’un projet git sous Rstudio

ou “Branchement” de Rstudio avec le projet sous GitLab

On va configurer notre projet Rstudio pour fonctionner avec notre projet GitLab.
Pour ce faire on va renseigner l’URL git+ssh du projet GitLab dans le projet Rstudio ce qui permettra à Rstudio (via GIT) de synchroniser votre version locale et celle du serveur GitLab (votre dépôt).

L’URL

L’URL demandé correspond à l’URL de votre projet GitLab. Elle est accessible via le bouton “Clone” sur la page du projet. Copie-colle l’URL Clone with SSH.

Mise en garde

Rstudio (via Git) va faire un git clone du projet GitLab en local.
Vous pouvez renommer (changer) la branche de travail du projet de master à main en effectuant ces commandes dans le terminal de Rstudio. (vous devez vous mettre d’accord pour le choix du nom de la branche sur laquelle vous allez travailler)
UN seul membre du projet doit effectuer cette modification (idéalement le même que précédemment).

cd mon_repertoire_projet
git switch -c main

Il est possible d’associer un projet Rstudio existant à un projet GitLab.
Pour ce faire placer vous dans votre projet Rstudio et le Terminal.

cd mon_repertoire_projet
git init
git switch -c main
git remote add origin git@gitlab.paca.inrae.fr:<MON_URL>.git
Important

Rstudio ne gère pas très bien l’intégration de Git, il se peut que vous deviez redémarrer votre session pour que cela soit pris en compte.
Regarder l’onglet de la fenêtre de droite “Git”.

Mon premier commit/push

Utiliser le format .md (markdown) dans le README. Plus d’information sur ce format ici.
Exemple d’un README.md pour {ggplot2}.

Schéma de cette étape

Création du README.md

Démarche
  • Un premier membre du projet crée un fichier texte appelé README.md à la racine du projet (le dossier du projet) sous Rstudio.
    • Dans ce fichier il renseigne un titre, une description du projet et/ou du package, ainsi que son Nom, Prénom, email et identifiant @id.
    • Sauvegarder le fichier.
Etat du projet
  • Remarquer que le fichier README.md apparaît avec l’icone A pour Add ou M pour Modified.

  • Vous pouvez voir ceci dans le terminal via la commande

git status
  • Pour versionner le fichier README.md cocher la case dans la colonne “staged”.
  • Mettre un message de Commit, puis cliquer sur Commit.
  • Finalement pour mettre à jour le dépôt distant (ici votre projet GitLab) cliquer sur Push.

Il est possible que Rstudio ne voit pas très bien votre dépôt git et empêche de faire des actions. (En faite, Rstudio n’a pas la référence de la branche sur le dépôt distant, car effectivement vous venez de la créer en local. Dans ce cas de figure Rstudio ne permet pas de faire un push/pull). Vous pouvez essayer de faire le push directement dans le terminal et redémarrer votre session Rstudio.
Pour ce faire placer vous dans votre projet Rstudio et le Terminal.

cd mon_repertoire_projet
git push -u origin main
Note

Observer votre projet sous GitLab.
Que s’est-il passé ?

Démarche pour les autres membres

Démarche pour les autres membres

Les autres membres font de même depuis leurs sessions / comptes Rstudio chacun son tour.

Configuration Rstudio
  • Effectuer l’étape Création d’un projet git sous Rstudio (sans le renommage de la branche)
    OU
  • Si vous avez déjà fait cette étape il faut mettre à jour votre git local (les objets et les références).
    Dans votre Terminal sous RStudio
git fetch
git pull origin main
  • Mettre à jour votre version locale (Bouton Pull)
  • Compléter/ajouter vos informations dans le README.md (Nom, Prénom, email et identifiant @id)
  • Sauvegarder, Commit et Push.
Mise en garde

Pour éviter des conflits et travailler avec une version du projet à jour (en local) il faut faire un Pull avant toutes choses.

Il est possible de faire les actions git directement dans le terminal sans passer par l’interface.
Pour ce faire placer vous dans votre projet Rstudio et le Terminal.

cd mon_repertoire_projet
git add README.md
git commit -a -m "Modification du README.md"
git push -u origin main
git pull origin main

Faire un rafraichissement de l’interface git de Rstudio pour voir les modifications.

Gestion des conflits de merge

Vous n’arrivez plus à faire un Pull ?

Comment se produit un conflit de merge ?

Un conflit de merge survient quand la version commit d’un fichier en local différe avec le dépôt distant (le projet GitLab dans notre cas) sur la/les mêmes lignes du fichier.
Simplement dit, les modifications locales d’un fichier (même la suppression) empêche sa mise à jour (pull) car le fichier a été modifié par quelqu’un d’autre (qui a mi cette version sur le dépôt GitLab avant vous).

$ git status
On branch main
Your branch and 'origin/main' have diverged,
and have 1 and 1 different commits each, respectively.
 (use "git pull" to merge the remote branch into yours)

You have unmerged paths.
 (fix conflicts and run "git commit")
 (use "git merge --abort" to abort the merge)

Unmerged paths:
 (use "git add <file>..." to mark resolution)
    both modified:   README.md

no changes added to commit (use "git add" and/or "git commit -a")

Quand il y a conflit de merge deux possibilités s’offrent à vous:

    1. (fix conflicts and run "git commit") : résoudre le conflit et commit les modifications
    1. git merge --abort : pour annuler le merge (mais ne résoudra pas le problème)

Résoudre un conflit de merge

Lors d’un conflit de merge, Git va fusionner les modifications (locales et distantes) dans le fichier et vous notifier cela dans le fichier.

Voici a quoi ressemble un conflit de merge dans un fichier.

README.md
## Titre
<<<<<<< HEAD
La description de notre projet
=======
Notre projet permet de régler le conflit de merge facilement.
>>>>>>> b7c82f75db73fc5aec7ffc2ef175253133876599

Explications :

  • Les chaînes de caractères <<<<<<< et >>>>>>> balisent la zone de conflit
  • La première partie du texte qui suit le mot HEAD correspond à la modification locale
  • La chaîne ======= indique la fin de cette modification, et il s’ensuit la modification distante (gitlab) en conflit
  • Le texte b7c82f75db73fc5aec7ffc2ef175253133876599 correspond au numéro d’identification unique du commit d’où provient le texte en conflit (gitlab)

Il existe trois solutions pour régler le conflit:

    1. Garder uniquement ses modifications (la version locale) git checkout --ours README.md
    1. Garde uniquement les modification distantes (GitLab) git checkout --theirs README.md
    1. Modifier le fichier et faire une nouvelle version. Il faut enlever les lignes ajoutées par Git et conserver le texte de son choix

Par exemple le fichier README.md devient:

README.md
## Titre
Notre projet permet de régler le conflit de merge facilement.

Par la suite il suffit de marquer le conflit du fichier résolu git add README.md

On appliquera cette procédure pour n’importe quel autre fichier en conflit.
Une fois tous les conflits résolus :

  • git commit
  • git push

Création d’une issue pour le projet

Note

Une issue permet la gestion/planification des tâches à effectuer, la remonté des bugs et les améliorations qui peuvent être effectuées.
En gros ce sont des “fiches” qui permettent de garder mémoire de toutes informations utiles en lien avec le projet.

  • Faire ceci ensemble (1 issue doit être créé)
  • Aller dans son projet GitLab -> menu de gauche Plan -> issue et créer une nouvelle issue (en markdown).
    • Cette issue sera votre référence principale sur l’avancé du projet.
      Le titre sera “Rendu de notre projet ”.
      En commentaire/description noter ce qu’il vous reste à faire pour finir le projet.
      exemple :
1. [ ] Initialiser un package / projet GitLab  
2. [ ] Implementer le package  
    1. [ ] exporter une fonction R  
    2. [ ] inclure mon application Shiny  
2. [ ] Implementer des tests sur mon package  
    1. [ ] Testthat  
    2. [ ] CI/CD  
3. [ ] Documenter mon package  
    1. [ ] Roxygen  
    2. [ ] pkgdown  
    3. [ ] automatiser la doc  
4. [ ] containeriser mon application Shiny  
  [ ] Dockerfile CI/CD  
  [ ] déploiement en production  
5. [ ] embarquer une application R Shiny  
  [ ] 1 widget  
  [ ] 1 carte   
  [ ] widget et carte intérragissent ensemble  
  [ ] 1 fonction de l'application Shiny provient du package  
6. [ ] Ajouter du contenu cool  
...
  • “Tagger” vos iud dans le haut de la description de l’issue (@id).
  • Ajouter le Milestone “Rendu du projet final” à l’issue (il faut créer la milestone).
  • Ajouter la date de rendu (maximum 15/01/2025).

-> Valider

Astuce

Par la suite vous pourrez mettre à jour l’issue, en créer de nouvelles et y ajouter des commentaires pour que vos camarades de projet puissent savoir ce que vous avez fait récemment dans le projet.
En cas d’interrogation vous pouvez me tagger @jfrey pour que je sois notifié dans vos commentaires.

Par la suite

Pensez à ajouter / valider des taches correspondants aux TPs et à vos améliorations.


Maintenant vous disposez d’un projet Git sous GitLab et Rstudio. Vous allez pouvoir versionner votre travail et travailler plus facilement en binôme.


Avant d’aller plus loin

Important

Envoyer un email à avec :

pour objet : [BUT3] <Nom_du_projet>

Contenu de l’email :

  • Titre : “Projet <nom_du_projet>”
  • Description : le lien sur la page du projet (URL) et les noms, prénoms avec les @id des membres du binôme
  • Toutes informations complémentaires

Si vous changez de dépôt par la suite penser à renvoyer un email

Pour finir

  • Créer une issue dans votre projet, avec pour titre “TP1”.
  • Ajouter le message et la version du commit correspondant à ce TP
    (menu de gauche -> Code -> Commits) le commit correspond à la clé SHA.
  • Dans le menu de gauche Code -> Tags, créer un Tags TP1 correspondant au commit du TP1.
  • Répondez aux questions suivantes dans la description de l’issue :
    • Qu’est-ce que Git ? Que permet de faire Git ?
    • Qu’est-ce qu’un projet GitLab ? Quel est son lien avec Git ?
    • A quoi peut servir une clé SSH ?
    • Comment Rstudio synchronise votre projet avec GitLab ?
    • Connaissez-vous d’autres outils de versionnement ? et/ou comme GitLab ?
  • Ajouter cette issue comme items liés (Linked items) à l’issue Rendu de notre projet (utiliser le nom de l’issue ou son numéro)

Pour aller plus loin

  • Explorer les menus de votre projet GitLab. (Rechercher une explication)
  • Explorer et rechercher des informations sur github.com. (noter cela dans une issue le cas échéant)
    • son écosystème
    • son utilisation par la communauté R
  • TP2