CSC 4102 – Introduction au génie logiciel pour applications orientées objet

Vous vous connectez à la plateforme GitLabEns de TSP (https://gitlabens.imtbs-tsp.eu) en utilisant l'authentification Shibboleth repérée par le bouton suivant :

La première page sur laquelle vous arrivez est votre page d'accueil et ressemble à l'image suivante.

Plutôt que de créer un projet en partant de zéro, vous partez d'un modèle de projet préparé pour le module. Ci-après, vous recopiez ce projet GitLabEns (par l'opération fork). Ce modèle de projet contient notamment un dépôt Git déjà peuplé.

Parcourez la liste des projets (onglet Projects dans le haut de la page à côté de l'onglet Your work). En commençant à taper csc4102... dans le formulaire de recherche, vous devez voir le projet enseignants.csc4102/csc4102-projet.

Ouvrez la page du projet enseignants.csc4102/csc4102-projet. Au dessus du bouton Clone, vous devez voir le bouton Fork (ou « Fourcher ») de l'image qui suit. Cliquez sur le bouton Fork.

Sélectionnez votre compte utilisateur comme « namespace » de la copie du projet. Profitez-en pour demander que le projet à créer soit privé.

En haut de la page du nouveau projet, un bandeau de couleur bleue affiche le message « The project was successfully forked. » comme montré dans l'image qui suit. Notez aussi que la page du projet indique la mention « Forked from enseignants.csc4102 ».

Si ce n'est pas déjà fait, dans le menu du projet à gauche, suivez l'entrée « Settings > General », puis Expand à la section Permissions. Rendez votre projet « privé » : Project Visibility > Private, et à la fin de cette section, Save changes. Le non-respect de cette règle revient à vous exposer aux mesures du paragraphe « Fraude » du règlement de scolarité.

Le second membre du binôme est à ajouter avec le rôle « Owner » afin que chaque membre du binôme ait le même rôle. Les personnes suivantes sont à ajouter à votre projet avec le rôle « Developer », voire « Maintainer » :

• pour le groupe de TP 1 : Chantal Taconet (en tant que responsable du groupe de TP) et Denis Conan (en tant que coordinateur du module),
• pour le groupe de TP 2 : Georgios Bouloukakis (en tant que responsable du groupe de TP) et Denis Conan (en tant que coordinateur du module),
• pour le groupe de TP 3 : Denis Conan (en tant que responsable du groupe de TP et en tant que coordinateur du module),
• pour le groupe de TP 4 : Élisabeth Brunet et Sophie Chabridon (en tant que responsables du groupe de TP) et Denis Conan (en tant que coordinateur du module),
• pour le groupe de TP 5 : Paul Gibson (en tant que responsable du groupe de TP) et Denis Conan (en tant que coordinateur du module),
• pour le groupe de TP 6 : Olivier Berger et Michel Simatic (en tant que responsable du groupe de TP), et Denis Conan (en tant que coordinateur du module).

Pour ce faire, retrouvez dans le menu du projet à gauche l'entrée « Manage » puis « Members ». Cette entrée de menu vous conduit à la page de gestion des membres du projet. Dans cette page listant les membres, sélectionner le lien « Invite members » pour rechercher les nouveaux membres parmi les utilisateurs connus par la plateforme. Ajoutez d'abord votre binôme comme indiqué dans l'image qui suit.

Enfin, ajoutez les membres de l'équipe enseignante cités ci-avant avec le rôle « Developer », voire « Maintainer ».

Lorsque vous travaillez, vous n'êtes pas forcément avec votre binôme et avec vos encadrants. Aussi, GitLab propose une fonctionnalité qui consiste à envoyer un courriel d'annonce à tous les membres du projet lorsque des modifications sont poussées sur le dépôt Git de GitLabEns.

Dans le menu du projet à gauche, sélectionnez l'entrée « Settings > Integrations », puis la page Emails on push.

Comme présenté dans l'image qui suit, configurez le service pour le rendre « active » sur les événements « Push » et « Tag push » avec l'adresse de l'émetteur étant celui qui pousse (case « Send from committer » cochée), et ajoutez les adresses courriels de tous les membres du projet (les deux membres du binôme ainsi que les membres de l'équipe enseignante que vous avez ajoutés à votre projet) dans le formulaire « Recipients ». N'oubliez pas de valider la nouvelle configuration avant de quitter la page.

Dans le menu GitLab de configuration de votre compte (non du projet) qui est accessible en haut à gauche à partir de l'image iconique de l'avatar de votre compte, sélectionnez l'entrée Profile. Puis, dans le menu à gauche de la page ouverte, suivez l'entrée « SSH Keys ». Vous arrivez sur une page contenant un formulaire pour enregistrer une clé publique : cf. l'image qui suit.

Sur la machine en salle TP, affichez dans la console votre clef publique par exemple avec la commande « cat ~/.ssh/id_rsa.pub ». Assurez-vous que le copier/coller contienne toute la clef : de la chaîne de caractères « ssh-rsa » à l'identifiant inclus. Remarquez lors du copier/coller dans l'interface Web de GitLab que l'identifiant devient ce que GitLab appelle le « titre » de la clef.

Lorsque vous ajoutez votre clé publique, GitLab vous envoie un courriel ayant pour sujet « SSH key was added to your account ».

Pour vérifier que votre clef est correctement installée, nous vous demandons d'exécuter une commande ssh dans un terminal. Lors de la première connexion SSH à la machine git@gitlabens.imtbs-tsp.eu, la commande ssh pose la question « Are you sure you want to continue connecting (yes/no)? » sur la vérification de la clef publique de la machine distante. Veuillez vérifier que l'empreinte (en anglais, fingerprint) est l'un des suivants (il existe plusieurs algorithmes de prise d'empreinte [fonctions de hachage] que votre client SSH peut utiliser) :

Pour information, la DISI publie (un sous-ensemble des) les informations ici.

Voici maintenant la commande ssh que vous exécutez pour vérifier la mise en place du chemin de confiance entre la machine qui exécute la commande ssh et la machine qui fournit le dépôt Git gitlabens.imtbs-tsp.eu.

Pour le suivi, l'équipe enseignante a accès à votre projet GitLabEns. L'équipe enseignante utilise des scripts pour faciliter le suivi. Ces scripts se basent sur les informations suivantes que vous envoyez par courriel à votre responsable de groupe ainsi qu'au coordinateur du module. L'URL de votre projet pour un accès SSH est présenté sur la page d'accueil de votre projet. Voici les indications pour le courriel à envoyer :

- destinataires : 
  - vous
  - votre binôme
  - les membres de l'équipe enseignante : cf. liste ci-avant pour votre groupe de TP
- sujet : CSC4102, groupe de TP X
- corps :
  - URL HTTPS de votre projet GitLabEns : à copier/coller à partir de la page d'accueil
    de votre projet avec le bouton "code" puis "clone via HTTPS"
    (cette URL est de la forme https://gitlabens.imtbs-tsp.eu/xxx.yyy/csc4102-projet
    avec « xxx.yyy » qui sont les nom et prénom du membre du binôme qui a créé le projet [par fork])
  - URL SSH de votre projet Git sur GitLabEns : à copier/coller à partir de la page d'accueil
    de votre projet avec le bouton "code" puis "clone via SSH"
    (cette URL, appelée "URL_SSH_VOTRE_PROJET_GIT" ci-après ;
    l'URL est de la forme : git@gitlabens.imtbs-tsp.eu:xxx.yyyy/csc4102-projet.git
    avec « xxx.yyy » qui sont les nom et prénom du membre du binôme qui a créé le projet [par fork])

Sur votre machine personnelle, re-parcourez l'étape 2.a.

Avant de commencer à utiliser les commandes Git, nous complétons l'installation Git.

Certaines commandes Git que nous étudions dans la suite du TP, par exemple git commit et git merge, demandent la saisie d'un message de log dans un éditeur de texte. Par défaut, Git utilise l'éditeur de texte configuré pour le shell. Le choix de l'éditeur de texte est contrôlé par les variables VISUAL et EDITOR. Vous avez deux possibilités : (1) fixer les variables VISUAL et EDITOR à la valeur « emacs » ou (2) demander à Git de ne pas utiliser l'éditeur par défaut mais emacs. Si votre éditeur de texte favori est emacs, nous vous conseillons de faire les deux manipulations qui suivent.

Git demande que vous indiquiez vos nom et adresse courriel pour les ajouter comme méta-données aux opérations de validation des instantanés (git commit). Exécutez les commandes qui suivent :

Lors de la récupération des contenus modifiés par les autres membres du projet, Git demande à utiliser une procédure de réconciliation automatique de l'historique de votre projet. Nous proposons d'utiliser la méthode dite de fusion (pour les connaisseurs, plutôt que le rebasage ou l'avance rapide) : en quelques mots, toujours pour les connaisseurs, on garde les instantanés sans les changer. Nous vous proposons donc d'exécuter la commande qui suit :

Enfin, pour résoudre les conflits lors des fusions (cf. ci-dessous), Git peut utiliser un outil graphique. Nous proposons d'utiliser l'outil meld. Exécutez la commande qui suit :

Avec la commande git clone, récupérez dans votre espace de travail (à l'intérieur du répertoire ~/CSC4102) une copie du dépôt Git de votre projet. C'est dans cette copie conforme (un clone) que vous travaillez.

Comme indiqué par l'affichage du message de la commande git clone, le dépôt n'est pas vide, mais contient le contenu initial qui vous est proposé pour démarrer le projet (vérifiez avec la commande ls -R).

Nous vous proposons de démarrer tout de suite l'outil gitk afin de visualiser l'historique des modifications du dépôt depuis le début de sa création (avant le fork). Dans toute la suite du TP, nous utilisons cet outil pour suivre la création des instantanés. C'est pour cela que vous devez démarrer gitk en arrière plan (« & »). Ceux qui préfèrent l'affichage en console de l'arbre des instantanés utiliseront la commande git log --graph --oneline ou l'outil tig.

Ajoutez votre premier contenu avec par exemple un fichier classique listant les participants au projet.

Le nouveau fichier n'est pas encore sous suivi de version. La commande git status nous le dit :

Comme montré dans l'image qui suit, l'outil git gui donne graphiquement les mêmes informations que la commande git status.

Ajoutez ce nouveau fichier dans la zone de transit :

À nouveau, l'outil git gui donne graphiquement les mêmes informations que la commande git status. Dans la suite de la présentation, par économie visuelle, nous préférons utiliser git status.

Et maintenant, validez ce premier ajout pour construire votre premier instantané du dépôt Git :

Nous pouvons aussi voir notre premier instantané avec « gitk --all » en demandant la mise à jour du graphe présenté : menu Fichier > Mise à jour ou touche F5.

Pour la suite des étapes, nous vous laissons vérifier l'effet de vos manipulations en utilisant à votre guise les commandes git status et gitk --all, voire git gui.

Dans cette étape, nous explorons l'ensemble des états possibles des entrées (cf. section 2.3 des diapositives du cours). Pour ce faire, nous commençons par ajouter un nouveau fichier (état « non suivi » [untracked]). Puis, nous ajoutons la nouvelle entrée à la zone de transit (staging area). L'entrée est alors dite indexée (cached ou staged). Enfin, nous modifions à nouveau le fichier qui est dans la zone de transit ; cela a pour effet d'avoir « trois versions » du même fichier : la « version » correspondant à l'instantané (snapshot) courant du répertoire de travail, la « version » correspondant à la zone de transit (c'est-à-dire celle qui sera dans la prochaine validation [commit]), et la « version » en cours de modification et dont les modifications ne font pas partie de la prochaine validation.

Nous utilisons la commande git status après chaque commande pour suivre ce qui se passe.

Nous avons référencé la page de la documentation de référence dans la rubrique « Trucs & astuces » pour Git à la question « Des informations sur le cycle de vie des états des fichiers ».

À la fin de cette courte séquence, vous avez approximativement la visualisation suivante dans l'outil gitk.

Vous avez du code écrit en JAVA dans votre dépôt : c'est l'ossature de départ de l'application contenue dans le répertoire src. Il est inutile dans ce cas d'encombrer le dépôt avec les fichiers résultant de la compilation, c'est-à-dire les fichiers *.class. En outre, si vous utilisez Eclipse, vous pouvez voir apparaître des répertoires spécifiques à Eclipse, par exemple un répertoire bin. Nous ne mettons pas non plus le workspace Eclipse dans le dépôt : pas de répertoires workspace ou .metadata. Par ailleurs, nous souhaitons ignorer les répertoires doc créés lors de la génération de la documentation Javadoc par Eclipse.

Toutes ces informations sont mises dans un fichier .gitignore, qui est ajouté à la racine de l'arborescence de votre dépôt. Par simplicité, nous avons choisi d'ajouter ce fichier dans le répertoire à la racine de l'arborescence du dépôt ; un autre choix serait de mettre plusieurs fichiers .gitignore pour les différentes sous-arborescences du dépôt.

Pour vérifier le fonctionnement de la configuration du fichier .gitignore, créez de manière artificielle (c'est-à-dire sans compilation) un fichier A.class.

Il est bien sûr possible de forcer l'ajout d'un fichier qui est par défaut ignoré : par exemple, avec git add -f A.class. Nous pouvons ensuite en profiter pour utiliser la commande git mv pour déplacer ou renommer le fichier et la commande git rm pour supprimer cette entrée. Dans notre scénario, comme le fichier à supprimer est déjà dans la zone de transit, nous devons ajouter l'option -f pour forcer la suppression. Nous terminons la séquence avec la commande git log qui fournit un historique des modifications.

Il arrive que l'on souhaite retirer des modifications effectuées par erreur alors qu'elles sont déjà indexées, c'est-à-dire alors que les fichiers correspondants ont été ajoutés à la zone de transit. Lorsque nous souhaitons que les modifications ne fassent plus partie de la prochaine validation, tout en n'annulant pas les modifications en elles-mêmes, nous utilisons la commande git restore --staged. Une fois le fichier sorti de la zone de transit, si nous souhaitons en plus que les modifications soient annulées, c'est-à-dire que nous souhaitons revenir à la « version » du dépôt dans le dernier instantané, alors nous utilisons la commande git restore. De manière assez simple, la commande git status, dans sa version par défaut verbeuse, nous indique les commandes à utiliser.

Depuis le début des manipulations du dépôt Git, nous ne l'avons pas dit, mais vous êtes dans la branche main, qui est la branche créée au démarrage du dépôt. Dans le scénario virtuel qui suit, vous créez une première branche de travail (sprint0). Ensuite, vous indiquez dans un fichier la liste des tâches du Sprint 0. Enfin, vous simulez les opérations de la tâche 1 :

1. création d'une branche tache1 (pour être « tranquille »),
2. déplacement dans la branche tache1,
3. travail sur la tâche,
4. validation de ce travail,
5. retour dans la branche du sprint (sprint0), et
6. fusion de la branche de la tâche (tache1).

Normalement, les messages en sortie fournis par les commandes sont assez explicites. Notez que nous utilisons l'option --no-ff (no fast-forward) de la commande git merge afin de matérialiser la fusion dans un instantané dédié. Retenez aussi que vous pouvez observer le graphe des instantanés dans la console avec l'option --graph de la commande git log, l'option --oneline permettant de compacter l'affichage. Bien sûr, continuez aussi à utiliser « gitk --all » pour visualiser le graphe.

Imaginons que vous continuiez votre travail dans le Sprint 0 en passant de tâches en tâches, et que vous créiez un scénario menant à un conflit inévitable :

1. travail sur la tâche 2 dans une branche dédiée tache2 créée à partir de la branche sprint0 ;
2. travail sur la tâche 3 dans une branche dédiée tache3 créée elle-aussi à partir du même instantané de la branche sprint0. Cette fois-ci, le travail sur la tâche 3 impacte le travail sur la tâche 2. En d'autres termes, certains fichiers sont modifiés concurremment dans les deux tâches/branches.

Nous sommes maintenant dans une situation de conflit. Nous devons construire une version des deux fichiers en résolvant les conflits, c'est-à-dire sans les balises « <<<<<<< », « ======= » et « >>>>>>>> ». Nous pourrions faire cela en ouvrant un éditeur de texte. Nous choisissons de nous aider de l'outil de fusion meld. Voici la commande :

Dans l'image ci-après, le fichier en cours de traitement est F2. L'objectif de la résolution du conflit est d'aligner les trois versions en utilisant les flèches.

Choisissons par exemple la version du fichier de la branche de la tâche 3 (fichier F2_REMOTE_4365.txt). Nous obtenons l'image suivante.

Nous terminons l'étude du fichier F2 en enregistrant les modifications : bouton Enregistrer et menu Fichier, puis Save All. Ensuite, nous fermons la fenêtre et une autre fenêtre s'ouvre pour la seconde résolution de conflit : fichier tachesPourSprint0.txt. Nous opérons similairement en choisissant la version de la branche de la tâche 3.

Nous terminons notre scénario comme suit :

Pour terminer proprement l'exercice, revenez sur la branche main et fusionnez-la avec la branche sprint0.

Les modifications de l'étape précédente n'existent que dans le dépôt Git sur la machine ou sur le compte d'un membre du binôme. Poussez vos modifications, c'est-à-dire vos instantanés, sur le dépôt Git de la forge logicielle GitLabEns afin que par la suite les autres membres du projet (l'autre membre du binôme ainsi que les encadrants) en prennent connaissance et les récupèrent dans leur dépôt local.

Dans cette étape, utilisez le compte du second membre du binôme-projet, c'est-à-dire autre que celui utilisé à l'exercice précédent. Cela permet de présenter les commandes git fetch et git pull.

Comme demandé au début de l'étape précédente, le second membre du binôme-projet possède déjà une « copie » du dépôt. Le dépôt a évolué depuis le clonage. Le processus classique de reprise est le suivant :

• récupération des mises à jour,
• (au besoin) déplacement sur la branche sur laquelle on souhaite travailler,
• repositionnement sur le dernier instantané d'une branche.

Nous terminons donc la séance par la mise en place de l'arborescence de votre projet GitLab pour les séances à venir.

Créez la branche develop en utilisant la commande git checkout avec l'option -b pour créer la branche et vous déplacer dedans (c'est un raccourci des deux commandes git branch pour créer la branche puis git checkout pour se positionner dans la branche créée).

À la fin du TP, l'outil gitk donne une image comme la suivante. Observez :

• les branches, dont certaines sont locales (celles du travail sur les tâches de notre petit scénario ne sont pas dans le dépôt Git de GitLabEns car vous ne les avez pas poussées avec git push ; vous pourriez les supprimer avec la commande git branch -d tache1, etc.) ;
• la branche main du dépôt Git de GitLabEns (repérée dans gitk par le nom remotes/origin/main) est alignée avec (à jour de) vos modifications ;
• la branche develop du dépôt Git de GitLabEns (repérée dans gitk par le nom remotes/origin/main) est alignée avec (à jour de) vos modifications ; et
• que, de manière plus subtile dans l'affichage, on voit que vous êtes sur la branche develop car le texte de la boîte verte « develop » est en graisse forte (les autres non).

Dans l'interface Web de GitLabEns, vous pouvez voir la séquence de commits : dans la page d'accueil du projet, suivez l'entrée « Repository » puis Commits pour obtenir une page comme l'image suivante.