Tout ce qu'il faut savoir sur Git, GitHub & GitLab

Dans l'article précédent, j'ai parlé de certains des outils les plus importants que vous aurez besoin d'utiliser lorsque vous travaillerez sur des projets de Data Science, y compris les widgets Git dans VS Code. Dans cet article, nous allons démystifier l'outil Git qui permet le versioning de votre code ainsi que la gestion de repositories collaborative.

Le sommaire est le suivant :

1. Git & GitHub/GitLab
2. Votre 1er repository
3. Pushing et Pulling du code
4. Philosophie d'un projet Git
5. CI-CD avec GitLab

‍

Git & Github

Git est un outil de coding principalement utilisé pour trois raisons :

• Versioner votre code dans le temps
• Garder une trace des modifications effectuées
• Permettre des collaborations parallèles de plusieurs parties

Pour cela, git fonctionne en trois étapes :

1. Working directory : c'est le dossier local hébergeant tous les fichiers de votre projet, plus précisément le dossier dans lequel git a été initialisé
2. Staging directory : il note et indexe chaque document modifié
3. Git local repository : chaque changement effectué donne lieu à une version du document ou un snapshot qui peut être capturé et labellisé avec un message.

Avant de plonger dans les command-lines de git, voyons d'abord comment l'installer et le configurer.

Installation de Git

• Windows : téléchargez l'installateur Windows Git depuis le site web suivant
• Mac : la plupart des versions de MacOs ont déjà git installé.

Configuration de Git

Comme mentionné précédemment, git est un outil de versioning et de collaboration, il est donc important de savoir qui travaille sur chaque fichier du projet, c'est pourquoi vous devez configurer votre git avec votre nom et votre adresse mail :

git config --global user.name "Name"
git config --global user.mail "mail"

‍

Votre 1er repository

Créer votre premier repo Git

Une fois git installé et configuré, vous pouvez créer votre premier projet git avec les command-lines suivantes :

mkdir projectFolder
cd projectFolder
git init #initialize git on your project
git status
touch file.md # create new file
open file.md # open the file and modify it
git status # file untracked -> add it to git index
git add file.md
git commit -m "file.md modified ..."

Dans le paragraphe suivant, vous trouverez le graphe résumant les relations entre les différentes étapes.

Héberger votre repository sur GitHub/GitLab

Github ou GitLab sont des plateformes qui permettent d'héberger votre projet et de coordonner la collaboration multi-parties. Les étapes suivantes détaillent comment procéder :

1. Créez un compte sur GitHub/GitLab
2. Créez un nouveau Repository
3. Copiez son lien
4. Clonez-le dans un dossier sur votre ordinateur
5. Effectuez tous les changements nécessaires assignés à leurs commits
6. Pushez les changements vers GitHub/GitLab

NB1 : Les quatre premières étapes ne sont effectuées qu'une seule fois tandis que les 5ème et 6ème sont itératives (voir paragraphe suivant). NB2 : Il est également possible de pusher un dossier existant dans le répertoire github en utilisant :

git remote add origin gitAdress git branch -M master git push -u origin master

‍

Pushing et Pulling du code

Une fois que vous avez effectué tous les changements, vous voudrez partager votre travail vers le repository GitHub/GitLab afin de le rendre accessible aux autres membres de votre équipe. Voici les étapes à suivre :

• Modifiez le fichier sur votre ordinateur
• Exécutez :

git add file.extension #Add it to the git index:
git commit -m "message" #Commit the changes
git push #Push the changes to github

Vous voudrez également récupérer les derniers changements effectués par les autres en utilisant la command-line suivante :

git pull

Le graphe suivant représente la connexion entre le repository local et celui de GitHub/GitLab.

NB : Lors du push ou pull depuis GitHub/GitLab, vos credentials devront être renseignés.

Illustration

Dans le GIF suivant, je vais créer un dossier local dans lequel je vais initier un versioning git et également créer un fichier nommé README.md, puis ajouter et committer les changements. Ensuite, je vais créer un repo Github vers lequel je vais pusher le dossier local et vérifier si Github a été mis à jour :

Collaboration

Lorsqu'on travaille sur un projet complexe, chaque membre de l'équipe est généralement assigné à une tâche ou une feature sur laquelle il peut travailler indépendamment. Cela dit, chaque projet peut être vu comme plusieurs sous-projets gérés par différents membres.
Afin de coordonner leur travail, git utilise la notion de branches : la principale s'appelle master et d'autres branches peuvent y être mergées une fois que le travail sur elles est stabilisé. Les branches peuvent également être utilisées pour séparer la version production de celle de development, dans laquelle de nouvelles features sont constamment développées, d'où le nom. Voici un workflow intelligent pour combiner les deux :

Pour ce faire, vous pouvez utiliser le script bash suivant, une fois dans le repository git :

git branch # get current branch (master)

git checkout -b devBranch # create and switch to development branch

git checkout -b featureBranch devBranch # Create feature branch over the development branch
git add file.extension # Add changed file to staging
git commit -m "message" # commit the message

git checkout devBranch # switch back to development branch
git merge featureBranch # merge featureBranch into devBranch

git push origin featureBranch # push the changes on featureBranch to github/gitlab
git push origin devBranch # push the changes on devBranch to github/gitlab

Voici une illustration du branching et merging en utilisant le projet précédent :

Lors du merge de branches, certains conflits peuvent survenir, en particulier lorsque deux personnes ont travaillé sur le même fichier, dans ce cas vous devez

• Ouvrir le fichier soulevant les conflits
• Résoudre les conflits (Utilisez VSCode par exemple)
• exécuter :

git add .git commit -m "message"

NB 1 : les branches peuvent également être vues comme un moyen de contribuer à des projets open-source, c'est-à-dire dont le code est publié publiquement sur GitHub/GitLab.
NB 2 : Vous voudrez peut-être configurer une connexion SSH entre votre machine et votre repository GitHub/GitLab afin de rendre votre collaboration plus fluide.

Ignorer des fichiers

Dans certaines situations, certains fichiers doivent être conservés en local. Dans ce cas, le relative path de ces fichiers doit être ajouté au fichier .gitignore qui est automatiquement créé lors de l'initialisation de git. Github et Gitlab sont principalement conçus pour stocker du code, il n'a donc pas de sens de leur envoyer des bases de données ou des poids de Deep Learning, leurs chemins sont généralement ajoutés au fichier .gitignore.

WEIGHTS_DIR/ #ignoring the folder of DL weights
DATA_DIR/ # ignoring the folder of data

CheatTable

Pour rappel, il existe deux façons de gérer votre versioning git dans VS Code : soit via Gitlens, soit via votre terminal installé. Pour plus de détails, n'hésitez pas à visiter la documentation officielle de git.

‍

Philosophie d'un projet Git

Lorsque vous travaillez sur un projet, par exemple une app, il est de bonne pratique de considérer trois niveaux de coding/branching :

• Master branch : ou main branch qui héberge la version du code utilisée par les utilisateurs quotidiens de l'app (uniquement pour les releases)
• Dev branch : utilisée pour héberger les nouveaux développements et features prévues pour l'app
• Feature branch : créée chaque fois qu'une nouvelle feature est en cours de développement

NB : Si la dev branch est stabilisée, vous pouvez la mirror sur une autre branche qui peut être utilisée par les testeurs de l'app, dans une UAT phase par exemple, afin d'essayer les nouvelles features et éventuellement signaler des bugs.

Lignes directrices majeures

Étant donné le workflow décrit ci-dessus, voici quelques points importants à garder à l'esprit :

Master branch :

• Ne jamais commit en local sur master !
• Gardez la master branch protégée !

Dev branch :

• Ne jamais commit en local sur dev !
• Gardez la branche dev protégée !

Feature branch :

• Pushez toujours votre travail sur votre remote branch même s'il n'est pas terminé !
• Lorsque vous collaborez sur la même branche, évitez de travailler sur le même fichier ou la même fonction !
• Vérifiez le statut à chaque fois avant le staging : git status
• Vérifiez toujours si vous avez la version récente du code de dev

Travailler sur une nouvelle feature

c'est-à-dire créer une nouvelle branche à partir de la dev branch :

1. Vérifiez si vous êtes sur la dev branch :

git branch

• Si oui :

git --rebase origin/dev #Check if you are up-to-date
git checkout -b branchName

• Si non :

git checkout dev
git --rebase origin/dev
git checkout -b branchName

2. Effectuez vos changements, ajoutez-les et committez-les

3. Pushez votre travail vers votre remote branch :

git push --set-upstream origin branchName

4. Assurez-vous que votre branche est à jour par rapport à dev :

git checkout branchName
git pull --rebase origin/dev

Résolvez les conflits s'il y en a :

git add path_to_resolved_file
git commit -m "message"
git push #sends automatically to your remote branch

5. Créez une Pull Request dans GitHub/Gitlab et assignez un reviewer

NB : Rebase est une autre technique de merge qui maintient vos logs plus propres

Nous pouvons résumer le git flow décrit ci-dessus dans la figure suivante :

Une fois le merge effectué, vous devrez vous assurer que l'app fonctionne parfaitement et qu'il n'y a pas de régressions par rapport à la version précédente, en exécutant des tests automatiques. Et c'est pour cela que vous avez besoin de CI/CD !

‍

CI-CD avec GitLab

CI/CD signifie Continuous Integration and Continuous Delivery/Deployment. C'est une approche technique qui permet d'automatiser le processus de développement des apps en exécutant des tests qui vérifient si

• Les nouvelles features fonctionnent comme attendu
• Il n'y a pas de régressions sur les anciennes

Gitlab propose cette option, qui est liée à chaque projet et fournit des runners ou processus qui prennent en charge et exécutent les jobs CI/CD.

Le pipeline CI/CD est développé en suivant 3 étapes majeures :

1. Installation & Enregistrement des GitLab Runners
2. Créer, en local, un fichier yml détaillant les jobs/tests à effectuer
3. Pusher les jobs vers Gitlab

1. GitLab Runners

Comme mentionné précédemment, les runners sont des processus utilisés pour exécuter des tests prédéfinis. Il en existe 3 types :

• Shared runners sont disponibles pour tous les groupes et projets d'une instance GitLab.
• Group runners sont disponibles pour tous les projets et sous-groupes d'un groupe.
• Specific runners sont associés à des projets spécifiques.

Dans cet exercice, nous allons nous plonger dans les specific runners qui sont utilisés pour un projet à la fois. Pour configurer le specific runner manuellement, nous devons d'abord installer GitLab Runner. Pour ce faire, sur MacOS par exemple, nous pouvons utiliser brew :

brew install gitlab-runner #Install GitLab Runner
brew services start gitlab-runner # Install GitLab Runner as a service and start it.

Une fois le runner installé, nous devrons l'enregistrer auprès du projet en exécutant la commande suivante :

gitlab-runner register

Nous devons ensuite entrer les informations suivantes :

• L'URL de l'instance GitLab : très souvent https://gitlab.com/
• Le registration token : trouvé dans Repository > Settings > Runners
• Description pour le runner : une courte description du runner
• Tags associés au runner
• Executor : plusieurs options à considérer (Docker, ssh, shell…)

2. Fichier YML

Pour utiliser les services CI/CD de GitLab, vous devrez héberger votre projet sur la plateforme et avoir un fichier YAML à sa racine appelé .gitlab-ci.yml qui héberge la configuration CD/CD.

Les scripts sont regroupés en jobs, et les jobs s'exécutent dans le cadre d'un pipeline plus large. Vous pouvez regrouper plusieurs jobs indépendants en stages qui s'exécutent dans un ordre défini. Les tags sont utilisés pour sélectionner un runner.

variables:
  GIT_DEPTH: 1 #Shallows cloning: Last commit for each file of the project

stages:
  - build
  - test
  #- deploy

install-dependencies: #Job 1
  stage: build
  tags:
    - python
  script:
    - echo "Install dependencies"
    - conda install environment.yml

linting: #Job 2
  stage: test
  tags:
    - python
  script:
    - echo "check linting"
    - pylint

unit-tests: #Job 3
  stage: test
  tags:
    - python
  script:
    - echo "unit tests"

integration-test: #Job 4
  stage: test
  tags:
    - python
  script:
    - echo "Integration tests"

Avant de pusher votre fichier vers GitLab, vous pouvez d'abord vérifier sa syntaxe et valider sa configuration sur CI Lint.

3. Pipeline sur GitLab

Comme vu dans le fichier yml, la configuration de la CI/CD consiste à exécuter différents jobs appartenant à différents stages cités dans l'ordre chronologique : build, test et deploy. Les jobs du même stage s'exécutent en parallèle, tandis que les jobs du stage suivant s'exécutent une fois les jobs du stage précédent terminés avec succès. À chaque push vers GitLab, les jobs sont exécutés et la merge request est validée une fois que tous les jobs ont été calculés avec succès. Vous pouvez suivre l'exécution en vérifiant les CI/CD Pipelines :

NB : Vous pouvez utiliser des fichiers yml separate pour les branches master et dev si les tests ne sont pas similaires.

‍

Conclusion

Git est un outil très puissant utilisé dans le monde entier dans pratiquement chaque app, en particulier celles disposant d'équipes de développement multiples, d'où la nécessité de MAÎTRISER cette technologie afin d'avoir un pipeline de développement durable et robuste permettant une collaboration rapide et meilleure.