Introduction

Le guide ci-dessous décrit la procédure conseillée pour la contribution des membres non-permanent du LIS (stagiaires, étudiants, ingénieurs en CDD…) à des projets de développement logiciel menés au LIS. Ce guide se place du côté du contributeur non-permanent, la procédure à suivre du côté l’encadrant étant décrite sur cette page.

Cette procédure n’est cependant pas réservée aux membres non-permanents du LIS et ce mode de fonctionnement peut être retenu par n’importe lequel de ses membres.

Cette procédure est notamment pensée pour faciliter l’encadrement de membres non permanents par des membres permanents (enseignants/chercheurs, ingénieurs) et permettre un bon contrôle de la qualité des développements intégrés dans les projets.

IMPORTANT : si les développements réalisés par un stagiaire ont vocation à être diffusés ou valorisés, il est nécessaire de faire signer au stagiaire en fin de stage une annexe à la convention de stage de cession des droits de propriété intellectuelle. Un modèle pour la rédaction de cette annexe est disponible ici.

La procédure s’appuie sur l’utilisation du serveur GitLab du LIS et des dépôts Git qu’il fournit. L’ouverture d’un compte informatique au LIS pour le membre non-permanent est donc un préalable à la procédure.

Si l’utilisation de Git et de GitLab ne vous est pas familière, il vous est très fortement conseillé de consulter les pages sur Git et sur GitLab.

Initialisation du projet

Les étapes de la procédure à suivre par un membre non-permanent sont les suivantes :

• Connectez-vous au serveur GitLab du LIS.
• Créez un projet fourche (fork) du projet GitLab auquel vous devez contribuer. Si le projet GitLab original est privé, il est donc nécessaire pour le responsable du projet de vous donner préalablement accès au projet.
• Configurez le projet fourche pour qu’il soit privé et que le ou les encadrants aient accès au projet.
• Configurez les options de notification du projet original et du projet fourche à votre convenance. Vous voudrez probablement être notifié des événements sur le projet original de manière à pouvoir maintenir à jour votre dépôt si nécessaire, et votre encadrant voudra probablement être notifié des événements dans votre projet fourche pour suivre votre travail.
• Clonez le dépôt du projet fourche sur votre machine de travail :
  git clone git@gitlab.lis-lab.fr:user_name/project_name.git
• Ajoutez le dépôt du projet original comme dépôt distant de manière à permettre la synchronisation des évolutions du projet original si nécessaire :
  git remote add upstream https://gitlab.lis-lab.fr/original_name/project_name.git

Développement et partage du code avec votre encadrant

• Ne réalisez aucun développement dans la branche master de votre dépôt ou dans les branches qui existent dans le dépôt original. Utilisez une ou plusieurs branches spécifiques pour vos développements. Comme indiqué dans la page sur Git, nous vous conseillons d’utiliser une branche pour chaque nouvelle fonctionnalité développée.
  Dans l’exemple que nous présentons dans cette procédure, nous supposons que vous souhaitez contribuer à la branche target présente dans le dépôt original, et que vous effectuez le développement dans la branche feature dans le dépôt de votre projet fourche. Les noms target et feature sont bien entendu à adapter en fonction des noms pertinents pour votre projet. Dans la pratique, la branche target sera typiquement la branche master du dépôt original.
  Basculez donc sur une nouvelle branche avant de modifier le code, en partant de la branche du dépôt original à laquelle vous souhaitez contribuer :
  git checkout target
git checkout -b feature
Si par erreur vous avez oublié de réaliser ce changement de branche avant de débuter vos développements, voire même que vous avez déjà archivé (commit) des modifications dans la mauvaise branche, vous pouvez consulter ce guide pour réparer ce qui doit l’être.
• Réalisez le développement en archivant régulièrement vos modifications dans le dépôt local (le développement complet d’une nouvelle fonctionnalité peut correspondre à plusieurs commits) :
  git add .
git commit -m "A clear and useful commit message"
Si vous êtes peu familier de l’utilisation de Git (en particulier si vous êtes habitué à utiliser SVN), n’oubliez pas que Git utilise une zone de transit (staging area) qui implique d’utiliser la commande git add avant chaque commande git commit de manière à préciser les modifications à archiver. Dans l’exemple précédent on utilise « git add . » pour inclure les modifications de tous les fichiers dans le répertoire courant. Cette commande est bien sûr à adapter en fonction des modifications que vous voulez effectivement inclure dans votre commit.
  Lorsque vous développez une nouvelle fonctionnalité, n’oubliez pas que vos développements doivent inclure tous les éléments liés à cette fonctionnalité, en particulier les tests et les éléments d’intégration continue associés.
• Renvoyez également régulièrement vos commits locaux vers le dépôt Git du projet fourche GitLab (à la fois pour sauvegarder votre travail et pour profiter des outils en ligne de GitLab sur votre dépôt) :
  git pull origin feature  # facultatif si vous êtes seul contributeur sur la branche
git push origin feature
S’il y a plusieurs contributeurs à la branche feature il est possible que la première étape (pull) fasse apparaître des conflits. Vous pouvez consulter cette section pour plus d’information sur la gestion des conflits dans Git si nécessaire.
  Notez que c’est la dernière étape (push) qui permet de faire apparaître votre code dans votre projet fourche GitLab.
  C’est donc l’étape à réaliser lorsque vous souhaitez partager votre code avec votre encadrant. Ceci permet notamment d’utiliser l’interface de GitLab pour discuter de votre code et de vos modifications, par exemple en laissant des commentaires sur la page correspondant à un commit, ou encore en utilisant le système de ticket de GitLab dans votre projet fourche. L’encadrant peut également utiliser directement Git pour récupérer et utiliser votre code sur sa machine.
  Si l’intégration continue est configurée pour le projet, cette étape permet également de vérifier que les éléments d’intégration continue fonctionnent convenablement, et notamment que le logiciel passe sa suite de tests. Pensez à bien effectuer les corrections nécessaires dans votre code si vous recevez un rapport d’intégration continue négatif à cette étape.

Resynchronisation avec le projet original

Lorsque des modifications ont lieu sur le dépôt original, il est souhaitable d’intégrer rapidement ces modifications dans votre dépôt fourche afin d’éviter que votre base de code ne devienne trop différente de celle présente sur le dépôt original. Ceci permet en particulier de limiter les risques de conflits lors des fusions. Pour cela, suivez les étapes suivantes :

• Resynchronisez la branche target de votre dépôt local et du dépôt Git de votre projet fourche GitLab avec celle du dépôt original :
  git checkout target
git pull upstream target
git push origin target
• Fusionnez les modifications introduites dans la branche target dans la branche de travail (il peut y avoir des conflits à gérer) :
  git checkout feature
git merge target
• Renvoyez la branche vers le dépôt Git du projet fourche GitLab :
  git pull origin feature  # facultatif si vous êtes seul contributeur sur la branche
git push origin feature
Si l’intégration continue est configurée pour le projet, cette dernière étape permet notamment de contrôler le bon fonctionnement des éléments d’intégration continue. Pensez à bien effectuer les corrections nécessaires dans votre code si vous recevez un rapport d’intégration continue négatif à cette étape.

Préparation d’une demande de fusion

Lorsqu’une étape de développement est finalisée et que vous souhaitez renvoyer vos modifications vers le projet original, il est nécessaire de préparez une demande de fusion. Pour cela assurez-vous d’avoir bien archivé (commit) vos dernières modifications, d’avoir bien intégré les dernières modifications du dépôt original dans votre dépôt fourche avec la procédure de resynchronisation ci-dessus et d’avoir bien renvoyé (push) toutes vos modifications sur le dépôt de votre projet fourche.

Avant de faire une demande de fusion, assurez-vous bien que la suite de tests du logiciel passe dans son intégralité. Pour cela vous devez exécuter manuellement la suite de tests sur le code avant le dernier renvoi de vos modifications (push) si vous n’utilisez pas la plate-forme d’intégration continue de GitLab, ou alors vérifier que vous obtenez un rapport d’intégration continue positif si l’intégration continue est utilisée dans votre projet.

Après avoir réalisé les étapes précédentes, vous pouvez faire la demande de fusion (merge request) de la branche feature de votre projet fourche vers la branche target du projet original via l’interface web de GitLab depuis votre projet fourche. Cette demande apparaîtra alors dans le projet original et pourra être traitée par un de ses responsables pour intégrer vos modifications au dépôt principal.

(Optionnel) Remise en forme des commits avant fusion

Afin de rendre l’historique du code plus lisible et compréhensible, notamment pour faciliter l’étape de revue de code, il peut être souhaitable de réaliser une étape supplémentaire avant de faire la demande de fusion. Cette étape permet de modifier le commit sur lequel se base l’historique de la branche afin de se resynchroniser avec le dernier commit présent dans la branche cible et également de modifier le contenu des commits notamment en changeant leur ordre ou en en regroupant certains, ou encore en modifiant le contenu de certains messages de commit. Pour comprendre l’intérêt de cet étape, consultez la section sur la restructuration des commits dans la page sur Git.

Concertez-vous avec votre encadrant pour savoir si vous devez mettre en œuvre cette étape dans votre projet.

Les étapes à suivre sont les suivantes :

• Resynchronisez la branche target de votre dépôt local et du dépôt Git de votre projet fourche GitLab avec celle du dépôt original :
  git checkout target
git pull upstream target
git push origin target
• Créez une nouvelle branche qui sera utilisée pour la demande de fusion et qui contient les modifications de votre branche de travail (pour nommer la nouvelle branche nous proposons de préfixer le nom de la branche par mr/ d’après les initiales de merge request) :
git checkout feature
git checkout -b mr/feature
  
• Restructurez vos modifications sur la base de la dernière version de la branche cible (voir la section sur la restructuration des commits pour l’utilisation de rebase --interactive) :
  git rebase --interactive target
• Renvoyez cette nouvelle branche sur le dépôt de votre projet fourche :
  git push origin mr/feature
Si l’intégration continue est configurée pour le projet, cette dernière étape permet notamment de contrôler le bon fonctionnement des éléments d’intégration continue. Pensez à bien effectuer les corrections nécessaires dans votre code si vous recevez un rapport d’intégration continue négatif à cette étape.

Vous pouvez alors faire la demande de fusion à partir de la nouvelle branche mr/feature qui vient d’être créée.

Poursuite après gestion d’une demande de fusion

Deux cas de figure peuvent se présenter suite à votre demande :

Demande de fusion acceptée

Après que la demande de fusion a été acceptée dans le projet principal, pensez à resynchroniser la branche correspondante dans votre dépôt avec celle du dépôt original. Prenez également soin de poursuivre vos développements dans une branche qui est bien synchrone avec cette dernière version (démarrez éventuellement une nouvelle branche si nécessaire).

Demande de fusion refusée

Si vous avez utilisé une branche mr/feature créée spécifiquement pour réaliser la demande de fusion :

• renommez la dans votre dépôt local de manière à la conserver temporairement pour référence :
  git branch --move mr/feature rejected/feature

• supprimez la branche correspondante du dépôt distant dans votre projet fourche GitLab :
  git push origin --delete mr/feature

Poursuivez votre développement en faisant les modifications nécessaires dans votre branche feature en fonction des indications qui vous ont été données par votre encadrant lors du refus de votre demande de fusion. Recréez si nécessaire une branche mr/feature pour préparer votre nouvelle demande de fusion, là encore en tenant compte des éventuelles indications qui vous ont été données.

Une fois votre développement finalisé et votre branche prête pour la fusion, faites une nouvelle demande de fusion via GitLab. Si elle est refusée reprenez les étapes ci-dessus, si elle est acceptée, vous pouvez supprimer la branche que vous aviez conservée temporairement :
git branch --delete rejected/feature

Entretien et nettoyage des dépôts Git

En utilisant Git comme nous le proposons, les dépôts peuvent rapidement contenir de nombreuses branches. Pour éviter la confusion et simplifier la gestion de vos développements, il peut donc être souhaitable de régulièrement entretenir et nettoyer les dépôts. Le type d’actions envisageables est par exemple le renommage de branches locales et distantes, notamment pour créer des groupes thématiques, ou encore la suppression de branches devenues inutiles (branches temporaires, expérimentations ponctuelles, branches utilisées pour des développements qui sont maintenant intégrés au projet principal…).

Pour réaliser cette maintenance, vous pouvez consulter la section correspondante sur la page de Git.

Fin du projet

Lors de votre départ du LIS, pensez à archiver ou supprimer votre projet fourche dans GitLab (voir la section « Settings » du projet). Le choix entre l’archivage et la suppression est à faire en accord avec votre encadrant.