Skip to article frontmatterSkip to article content
Site not loading correctly?

This may be due to an incorrect BASE_URL configuration. See the MyST Documentation for reference.

🖥️ Diapositives du cours — Séance 02 (ven. 2 oct.)

Le contrôle de version

Le contrôle de version est un système qui organise et suit les versions du code.

Les versions d’un article de recherche. Le nommage des fichiers et le suivi des modifications peuvent vite tourner au chaos. D’après PhD Comics.

Les versions d’un article de recherche. Le nommage des fichiers et le suivi des modifications peuvent vite tourner au chaos. D’après PhD Comics.

Il garde trace des modifications et de leurs auteurs. Voir la discussion approfondie du Turing Way the_turing_way_community_2022_6909298. En voici les points essentiels.

Illustration d'une branche principale

Figure 2:Illustration d’une branche principale (main branch), d’après The Turing Way [1].

À chaque commit (validation), git enregistre les modifications. Plusieurs personnes peuvent travailler sur le même fichier ; le contrôle de version reconnaît les conflits et propose de quoi les résoudre. La bonne pratique veut que la branche principale reste la branche la plus propre. Créez des branches supplémentaires pour travailler sur des parties précises du projet.

Illustration d'une branche secondaire créée, validée puis fusionnée.

Figure 3:Illustration de branches secondaires créées, validées puis fusionnées dans la branche principale. D’après The Turing Way [1].

Quelle différence entre git et GitHub ?

Configurer Git

Définissez votre nom d’utilisateur et votre adresse électronique :

git config --global user.name "superseismo"
git config --global user.email "superseismo@uw.edu"

Utilisez le même nom d’utilisateur que votre compte GitHub, pour que GitHub vous attribue vos commits. À faire une seule fois par machine.

GitHub

Créer un compte GitHub

Créez un compte GitHub avec les mêmes nom d’utilisateur et adresse que dans votre configuration git. Les comptes gratuits incluent un nombre illimité de dépôts publics et privés ; les offres payantes ajoutent des fonctions d’organisation et d’entreprise dont vous n’aurez pas besoin dans ce cours.

Authentification

GitHub impose l’authentification à deux facteurs (2FA) à tous les contributeurs — configurez-la à la création du compte, avec une application d’authentification, une clé d’accès (passkey) ou l’application GitHub Mobile. Le mot de passe du compte ne suffit jamais à authentifier les opérations git ; utilisez l’un des moyens suivants :

Plus de détails sur l’authentification GitHub ici. L’aide-mémoire git est une référence de commandes bien commode.

Obtenir une copie d’un dépôt existant

Il y a deux façons de partir d’un dépôt existant, et elles ne sont pas équivalentes :

Règle pratique : clonez les dépôts qui vous appartiennent ou sur lesquels vous pouvez écrire (votre dépôt MLGEO2026_UWNETID, le projet de votre équipe) ; forkez, puis clonez votre fork pour les dépôts où vous ne pouvez pas écrire (ce livre, la plupart des projets open source).

Créer un nouveau dépôt

Vous allez créer votre premier dépôt. Faites-le une seule fois, par l’une des trois méthodes suivantes.

Depuis le navigateur :

  1. Connectez-vous à GitHub. En haut à droite de n’importe quelle page, cliquez sur +, puis New repository.
  2. Nommez-le, choisissez public ou privé.
  3. Cochez Add a README file et choisissez une licence.
  4. Cliquez sur Create repository.
  5. Clonez-le sur votre ordinateur : git clone https://github.com/superseismo/my-repo.git

Depuis le CLI gh (une commande fait tout ce qui précède) :

gh repo create my-repo --public --add-readme --license mit --clone

Avec git seul, quand le code existe déjà dans un répertoire local : créez d’abord un dépôt vide sur GitHub (méthode navigateur, étapes 1–4, sans le README), puis

cd my-project
git init
git add .
git commit -m "first commit"
git remote add origin https://github.com/superseismo/my-project.git
git push -u origin main

Choisissez un chemin local hors des dossiers synchronisés avec le cloud (Dropbox, Google Drive) pour vous épargner des ennuis, puis ouvrez le dépôt dans VS Code ou votre éditeur préféré. Ce qui doit figurer dans un dépôt — README, licence, fichier CONTRIBUTING, spécification d’environnement — est couvert en 1.1 Science ouverte et reproductible ; les bonnes pratiques suivent software_carpentries_intermediate. Ajoutez tôt un fichier .gitignore pour que les gros fichiers de données et les sorties générées ne soient jamais validés.

Le cycle quotidien

Au quotidien, contribuer à un dépôt est une boucle de quatre commandes :

  1. Mettez à jour votre copie locale avant de commencer :

    git pull

  2. Éditez les fichiers dans votre éditeur, puis vérifiez ce qui a changé :

    git status
git diff

  3. Indexez et validez les modifications avec un message descriptif :

    git add <file1> <file2>       # ou : git add .  pour tous les fichiers modifiés
git commit -m "Votre message de commit descriptif"

    GitHub appelle staging (indexation) l’étape qui rassemble les modifications que le prochain commit enregistrera sur le serveur distant.

  4. Poussez les commits vers GitHub :

    git push

Exemple de flux de travail

Un passage complet dans la boucle, jusqu’à la pull request :

  1. Mettre à jour et brancher. Partez de la branche principale à jour et créez une branche de travail :

    git pull
git switch -c fix-readme

  2. Éditer. Ouvrez example.txt, faites vos modifications, relisez-les avec git diff.

  3. Indexer et valider :

    git add example.txt
git commit -m "Clarify installation instructions"

  4. Pousser la branche vers GitHub :

    git push -u origin fix-readme

  5. Ouvrir une pull request. Cliquez sur le lien que git affiche après le push, utilisez le bouton Compare & pull request sur la page du dépôt, ou lancez :

    gh pr create

    Une fois la pull request relue et fusionnée, revenez sur la branche principale et tirez le résultat fusionné : git switch main, puis git pull.

Annuler des modifications

Le git moderne sépare l’« annulation » en commandes explicites. Deux commandes sûres, d’usage quotidien :

Pour jeter vos modifications locales d’un fichier et revenir à la dernière version validée :

git restore mycode.py

Vous croiserez git checkout et git reset HEAD <fichier> dans des tutoriels plus anciens ; git restore (pour les fichiers) et git switch (pour les branches) les ont remplacés en 2019, parce que checkout faisait les deux à la fois et rendait les erreurs faciles.

Travailler en équipe

La branche principale doit rester la version propre et officielle, destinée au public.

Les pull requests avec GitHub. Tiré d’EarthDataScience. Source : Earth Lab, Alana Faller

Les pull requests avec GitHub. Tiré d’EarthDataScience. Source : Earth Lab, Alana Faller

Issues GitHub : utilisez le gabarit

Issues GitHub : utilisez le gabarit

Discussion complémentaire ici.

Structure de dépôt recommandée

Structure du dépôt

your-repo/ 
├── .github/ # GitHub-specific files (e.g., issue templates, workflows) 
│ ├── ISSUE_TEMPLATE/ # for sophisticated community package
│ ├── PULL_REQUEST_TEMPLATE.md  # for sophisticated community package
│ └── workflows/ 
│ └── ci.yml # Continuous Integration configuration, publish package, build container, test, build github-pages
├── docs/ # Documentation files 
│ ├── conf.py # Sphinx configuration file 
│ ├── index.rst # Main documentation file 
│ └── ... 
├── your_package/ # Main package directory 
│ ├── init.py # Package initialization
│ ├── module1.py # Example module 
│ ├── module2.py # Example module 
│ └── ... 
├── tests/ # Unit tests 
│ ├── init.py 
│ ├── test_module1.py # Tests for module1 
│ ├── test_module2.py # Tests for module2 
│ └── ... 
├── .gitignore # Git ignore file 
├── environment.yml # Conda environment file 
├── requirements.txt # Pip requirements file 
├── pyproject.toml # project TOML file for packaging 
├── README.md # Project README file 
├── LICENSE # License file 
└── CONTRIBUTING.md # Contribution guidelines

Explication des fichiers et répertoires clés

Exemple de pyproject.toml

C’est un standard plus récent, introduit par les PEP 518 et 621. Il vise une façon unifiée de spécifier les exigences du système de build et les métadonnées du paquet, dans l’effort de modernisation de l’empaquetage Python. Voici un exemple de pyproject.toml pour empaqueter votre projet :

[build-system]
requires = ["setuptools>=42", "wheel"]
build-backend = "setuptools.build_meta"

[project]
name = "your_package"
version = "0.1.0"
description = "A brief description of your project"
readme = "README.md"
requires-python = ">=3.11"
license = {text = "MIT"}
authors = [
    {name = "Your Name", email = "your.email@example.com"}
]
dependencies = [
    "numpy",
    "pandas",
]

[project.urls]
Homepage = "https://github.com/yourusername/your-repo"

[tool.setuptools]
packages = ["your_package"]

[project.scripts]
your_command = "your_package.module:function"

Cette structure garde un projet Python organisé et prévisible pour les collaborateurs. GitHub n’utilise pas directement le fichier pyproject.toml ; en revanche, vous pouvez configurer des GitHub Actions pour automatiser les tests, le build et la publication de votre paquet.

Commits générés par l’IA et relecture de code

En 2026, une grande partie du code qui atterrit dans un dépôt étudiant a d’abord été rédigée par un assistant IA, parfois sous forme d’un commit entier ou d’une pull request ouverte par l’agent lui-même. Le contrôle de version est l’endroit où vous en gardez la maîtrise. Trois règles pour ce cours :

Publier votre logiciel

Si le logiciel servira à des recherches futures et mérite d’être cité par la communauté, publiez-le sur Zenodo pour obtenir un DOI. Voir 1.1 Science ouverte et reproductible pour le processus, les licences et les pratiques de citation.

Exercice — répétition : votre première pull request

Les pull requests pèsent réellement dans ce cours : le classement (leaderboard) de la classe en 3.5 Classification multiclasse note des fichiers de prédiction que vous soumettez par PR. Cet exercice n’est pas noté, si bien que votre première PR notée ne sera pas votre coup d’essai. Il se déroule entièrement dans votre propre dépôt MLGEO2026_UWNETID (créé en 1.9), où une erreur ne coûte rien.

  1. Clonez votre dépôt (si ce n’est déjà fait) et créez une branche :

    git clone https://github.com/superseismo/MLGEO2026_UWNETID.git
cd MLGEO2026_UWNETID
git switch -c hello-world

  2. Ajoutez une ligne au README.md — par exemple une phrase sur ce que vous attendez de ce cours. Vérifiez la modification avec git diff.

  3. Validez et poussez la branche :

    git add README.md
git commit -m "Add hello-world line to README"
git push -u origin hello-world

  4. Ouvrez la pull request sur GitHub (ou gh pr create). Écrivez une phrase de description disant ce que change la PR.

  5. Relisez votre propre diff dans l’onglet Files changed — la vue qu’aura le relecteur de votre soumission au classement. Puis fusionnez la PR.

  6. De retour sur votre machine, synchronisez la branche principale et supprimez la branche fusionnée :

    git switch main
git pull
git branch -d hello-world

Résultat attendu : votre modification du README visible sur la branche principale sur GitHub, une PR fusionnée dans l’onglet Pull requests du dépôt, et une branche principale locale identique à la distante.

Ressources complémentaires

Le Turing Way offre d’excellentes ressources sur le contrôle de version.

Footnotes

  1. the_turing_way_community_2022_6909298

    ↩↩
Chapitre 1 — L'écosystème open source
1.4 Environnements de calcul
Chapitre 1 — L'écosystème open source
1.6 Galerie de données