TP1 : Prise en main de l’environnement de travail
BUT 3 - Domaines d’application
Prérequis
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.
Disposer des comptes Rstudio (sur https://guacamole.univ-avignon.fr/rstudio/) de chacun des membres du groupe projet.
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”.
Git est un outil libre et opensource de gestion de versions décentralisé créé en 2005 par Linus Torvalds.
Git sur wikipédia
Configurations
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 :
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
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
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.).
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)NoteDans 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).
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).
- UN membre du groupe doit une fois connecté à https://guacamole.univ-avignon.fr/rstudio
- Créer un nouveau projet de type Version Control -> git (avec pour URL l’URL de votre projet GitLab.
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.
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
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
Création du README.md
- 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.
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
Observer votre projet sous GitLab.
Que s’est-il passé ?
Démarche pour les autres membres
Les autres membres font de même depuis leurs sessions / comptes Rstudio chacun son tour.
- 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.
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 ?
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:
(fix conflicts and run "git commit")
: résoudre le conflit et commit les modifications
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:
- Garder uniquement ses modifications (la version locale)
git checkout --ours README.md
- Garder uniquement ses modifications (la version locale)
- Garde uniquement les modification distantes (GitLab)
git checkout --theirs README.md
- Garde uniquement les modification distantes (GitLab)
- 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
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 :
- Cette issue sera votre référence principale sur l’avancé du projet.
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
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.
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
Envoyer un email à jean-francois.rey@inrae.fr 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