Git, GitHub et contribution open source

Une question de départ

Deux étudiants travaillent sur le même fichier. L'un l'envoie à l'autre par messagerie ; l'autre répond avec « version finale 2 ». Trois jours plus tard, personne ne sait quelle version est la bonne. Git résout ce problème : il garde l'historique de chaque modification, qui l'a faite, quand, et pourquoi.

Ce qu'est un commit

Un commit est un instantané de tous les fichiers du projet à un moment donné, avec : un auteur, une date, un message, et un lien vers le ou les commits parents. Git identifie chaque commit par une empreinte calculée à partir de tout ce contenu, y compris l'empreinte du parent. Historiquement, cette empreinte est un SHA-1 ; Git sait aussi fonctionner avec SHA-256 (voir la note plus bas).

Comme pour une blockchain, changer un commit ancien change son empreinte, donc celle de tous ses descendants. Dans l'outil de hachage, modifiez une lettre d'un texte et observez : l'empreinte est totalement différente. Dans l'explorateur de chaîne, modifiez le bloc 2 : tous les suivants « cassent ». C'est la même idée.

Deux différences honnêtes avec une blockchain :

• Il n'y a pas de consensus. Chacun possède une copie complète et peut réécrire son historique local. La « vérité » du projet est ce que l'équipe a convenu de considérer comme dépôt de référence (en général la branche main du dépôt principal).
• Une empreinte Git identifie un contenu ; elle ne prouve pas qui l'a écrit (sauf signature de commit, voir leçon 4).

Les trois zones

dossier de travail  --git add-->  zone d'index (staging)  --git commit-->  dépôt (historique)

• git status montre ce qui a changé et ce qui est prêt à être validé.
• git add fichier choisit ce qui entrera dans le prochain commit (un commit = une idée, pas tout ce que vous avez touché).
• git commit crée l'instantané.

Branches : des étiquettes qui bougent

Une branche est un simple pointeur vers un commit. Créer une branche ne copie rien :

git switch -c feature/fees       # crée et se place sur la branche
git log --oneline --graph --decorate --all

Exemple de sortie :

* 9f3c2ab (HEAD -> feature/fees) Add fee estimate helper
* 41d7e90 Fix typo in README
| * c0a11fe (origin/main, main) Update CI node version
|/
* 7b2e5d1 Initial import

Lecture : à partir du commit initial 7b2e5d1, main a avancé d'un commit (c0a11fe) et feature/fees de deux. HEAD est la branche sur laquelle vous êtes. origin/main est ce que vous savez de main sur le serveur au dernier git fetch.

De bons messages de commit

Un message est lu des mois plus tard, par quelqu'un qui cherche pourquoi une ligne existe. Convention répandue (pas une loi) :

Reject negative amounts in transfer()

A negative amount credited the sender. Validate amount > 0
and add tests for -1 and 0.

Un sujet court à l'impératif (environ 50 caractères), une ligne vide, puis le pourquoi. Un message « fix » ou « WIP » n'apprend rien. Un commit qui mélange trois sujets ne peut pas être annulé proprement.

Réécriture maîtrisée

Git permet de réécrire l'historique : git commit --amend (le dernier commit), git rebase -i HEAD~3 (regrouper, renommer, réordonner trois commits). Chaque réécriture crée de nouveaux commits avec de nouvelles empreintes. Règle d'or :

• Réécrire est sûr tant que les commits sont à vous seul (pas encore poussés, ou sur votre branche de pull request que personne d'autre n'utilise). Pour pousser après réécriture : git push --force-with-lease (plus prudent que --force : il refuse si la branche distante a avancé depuis votre dernière récupération, par exemple parce que quelqu'un d'autre y a poussé ; un git fetch automatique de votre éditeur peut toutefois mettre à jour votre vue et neutraliser cette protection).
• Réécrire est interdit sur une branche partagée (main) : vos collègues ont bâti dessus.
• Pour défaire un commit déjà partagé, utilisez git revert <empreinte> : il crée un nouveau commit qui annule l'ancien, sans rien réécrire.

Filet de sécurité : git reflog liste les endroits où HEAD est passé, même après une réécriture, ce qui permet généralement de retrouver un commit « perdu » pendant un certain temps. git reset --hard, en revanche, jette définitivement les modifications non validées.

Ce que cela ne garantit PAS

• Un historique propre n'est pas un code correct : il dit ce qui a changé, pas que cela marche.
• Git ne prouve pas l'identité de l'auteur : le nom et l'e-mail d'un commit sont des champs que chacun peut écrire.
• git revert n'efface pas la trace d'un secret ou d'une erreur : l'ancien commit reste dans l'historique.

À retenir

Un commit = un instantané lié à son parent par une empreinte ; une branche = un pointeur. Réécrivez seulement ce qui est à vous seul, et utilisez revert pour ce qui est partagé.

Le problème

Amina et Paul modifient chacun le fichier de configuration d'un outil. Amina met les frais à 15 sur sa branche ; Paul, après discussion avec l'équipe, les met à 12 sur main. Quand Amina veut intégrer main, Git ne peut pas deviner qui a raison. Il s'arrête et demande : c'est un conflit. Ce n'est pas un échec ; c'est Git qui refuse de choisir à votre place.

Deux façons d'intégrer

Fusion (merge) : git merge main (depuis votre branche) crée un commit de fusion qui a deux parents. L'historique garde la forme réelle du travail, avec ses embranchements. Si votre branche n'a pas divergé, Git avance simplement le pointeur (fast-forward), sans commit de fusion.

Rebase : git rebase main rejoue vos commits un par un par-dessus le dernier commit de main. L'historique devient une ligne droite, mais vos commits reçoivent de nouvelles empreintes : c'est une réécriture (leçon 1). On rebase donc ses propres commits non partagés, jamais ceux d'une branche que d'autres utilisent.

Les projets choisissent leur politique (fusion, rebase, « squash » en un seul commit) : lisez le fichier CONTRIBUTING avant de choisir.

Anatomie d'un conflit

Après git merge main, Git affiche :

Auto-merging config.toml
CONFLICT (content): Merge conflict in config.toml
Automatic merge failed; fix conflicts and then commit the result.

Et le fichier contient :

<<<<<<< HEAD
fee = 15
=======
fee = 12
>>>>>>> main
timeout = 30

• Entre <<<<<<< HEAD et ======= : votre version (la branche où vous êtes).
• Entre ======= et >>>>>>> main : la version venant de l'autre branche.
• timeout = 30 est hors des marqueurs : Git l'a fusionné sans difficulté.

Résoudre : décider, éditer, valider

Rappel : l'équipe a décidé 12 (discussion dans le ticket). Les étapes :

1. Décidez quelle valeur est la bonne. Git ne peut pas décider ; ne prenez pas « la mienne » par réflexe.
2. Éditez le fichier pour qu'il contienne le résultat voulu, sans aucun marqueur :

fee = 12
timeout = 30

1. git add config.toml pour marquer le conflit comme résolu.
2. git merge --continue (ou git commit) pour terminer la fusion. Dans un rebase, ce serait git rebase --continue.
3. Lancez les tests. Une fusion sans marqueur n'est pas forcément correcte (voir plus bas).

Pour tout annuler et revenir à l'état d'avant : git merge --abort (ou git rebase --abort). C'est la sortie de secours.

Ne pas perdre de travail

• Avant une fusion risquée, validez (git commit) ou mettez de côté (git stash) vos modifications.
• Créez une branche de sauvegarde : git branch backup-avant-fusion ; elle ne coûte rien.
• Après la résolution, relisez avec git diff et lancez les tests.
• Si vous êtes perdu : git status dit exactement dans quel état vous êtes et ce qu'il faut faire ensuite. Puis git merge --abort.

Un conflit sémantique : sans marqueur, mais faux

Amina renomme la fonction compute_fee en estimate_fee sur sa branche. Paul ajoute sur main un nouvel appel à compute_fee dans un autre fichier. Git fusionne sans conflit, car les lignes modifiées sont différentes. Mais le code appelle maintenant une fonction qui n'existe plus : le programme échoue. Une fusion textuelle réussie ne garantit pas un programme correct, d'où l'étape « lancer les tests ».

Exemple chiffré

Deux branches modifient le même fichier de 200 lignes : B en change 10, C en change 4 (Git fusionne toujours deux branches à la fois). Si 3 lignes consécutives de C sont aussi modifiées par B, Git produit un seul bloc de conflit de 3 lignes ; si ces 3 lignes sont séparées par des lignes inchangées, il y a un bloc par groupe. Attention : des modifications de lignes adjacentes (la ligne 2 d'un côté, la ligne 3 de l'autre) sont déjà un conflit, même sans chevauchement ; il faut au moins une ligne inchangée entre deux zones modifiées pour que Git les fusionne seul (comportement observé avec Git 2.43 en réglage par défaut). Un conflit est un bloc de lignes, pas une ligne.

Ce que cela ne garantit PAS

• Résoudre un conflit n'est pas l'accord de l'équipe : si vous ignorez la décision du ticket, vous créez un bogue silencieux.
• git merge --abort ne récupère pas du travail que vous aviez jeté vous-même avec reset --hard.
• Un rebase propre ne dit rien de l'état des tests.

À retenir

Un conflit demande une décision humaine. Décidez, éditez sans marqueurs, add, continue, testez ; --abort est toujours possible ; sauvegardez avant de risquer.

Le problème

Vous voulez corriger une faute dans la documentation d'un dépôt qui n'est pas le vôtre. Vous n'avez pas le droit d'y écrire directement, et heureusement : n'importe qui pourrait alors casser le projet. Le flux standard permet de proposer un changement que les mainteneurs examinent avant de l'accepter.

Le flux, étape par étape

1. Fork : sur GitHub, vous créez votre copie du dépôt (le fork). Vous pouvez y écrire.
2. Clone : vous copiez votre fork sur votre machine.
3. Remote upstream : vous déclarez le dépôt d'origine comme second dépôt distant, pour le suivre.
4. Branche : vous travaillez sur une branche dédiée, jamais directement sur main.
5. Push : vous poussez la branche vers votre fork.
6. Pull request (PR) : sur GitHub, vous demandez que votre branche soit intégrée au dépôt d'origine.
7. Revue : les mainteneurs commentent ; vous répondez et corrigez ; ils acceptent ou non.

git clone <url-de-votre-fork>
cd depot
git remote add upstream <url-du-depot-d-origine>
git remote -v                          # origin = votre fork, upstream = l'original
git fetch upstream
git switch -c docs/fix-typo-install    # branche dédiée, nom parlant
# ... modifier, puis:
git add docs/install.md
git commit -m "Fix typo in install instructions"
git push -u origin docs/fix-typo-install

Ensuite, sur GitHub, ouvrez la PR : base = la branche principale du dépôt d'origine, compare = votre branche de votre fork.

Une bonne pull request

• Un seul sujet, petit. Plus une PR est grosse, plus elle est lente à relire et facile à refuser.
• Un titre clair et une description : quoi, pourquoi, comment vérifié. Si elle répond à un ticket, écrivez Closes #123 : à la fusion dans la branche par défaut, GitHub ferme le ticket 123 automatiquement.
• Les vérifications automatiques (CI) doivent passer. Elles sont décrites dans des fichiers de workflow ; voir la documentation de GitHub Actions.
• Lisez `CONTRIBUTING` avant d'écrire : style, tests, format des messages, parfois une signature Signed-off-by (git commit -s) ou un accord de contribution.
• Pour un gros changement, ouvrez d'abord un ticket pour demander si le projet en veut.
• Une PR en brouillon (draft) signale « pas encore prête à relire ».

Répondre à une revue

Le relecteur écrit : « Peux-tu ajouter un test pour le cas montant = 0 ? Et renommer tmp ? ». Bonne conduite :

1. Lisez chaque commentaire et décidez : j'applique, ou j'explique poliment pourquoi pas.
2. Faites les corrections sur la même branche et poussez : la PR se met à jour toute seule. Ne fermez pas la PR pour en ouvrir une nouvelle.
3. Répondez à chaque fil (« fait dans 3f2a9c1 » ou une explication) ; ne marquez « résolu » que ce qui l'est réellement.
4. Si le projet demande un historique propre, regroupez les correctifs avec un rebase interactif puis git push --force-with-lease — seulement sur votre branche de PR.
5. Redemandez la relecture une fois les points traités.

Une revue critique le code, pas la personne. Un refus d'une PR n'est pas un jugement sur vous : les mainteneurs doivent préserver la cohérence du projet. Si un désaccord persiste, demandez, ne polémiquez pas.

Tenir son fork à jour

Pendant que votre PR est en revue, main avance. Pour rester à jour :

git fetch upstream
git rebase upstream/main        # ou: git merge upstream/main, selon la politique du projet
git push --force-with-lease     # si vous avez rebasé votre branche de PR

Exemple chiffré : une PR trop grosse

Une PR change 1 200 lignes dans 14 fichiers, pour trois sujets. Un relecteur qui lit 200 lignes par séance y passera 6 séances et risque de n'avoir plus en tête le début à la fin. Découpée en trois PR de 400 lignes sur un seul sujet chacune, chaque PR est relue en environ 2 séances et peut être acceptée ou refusée séparément. Le total de lecture est le même ; le risque et le délai ne le sont pas.

Ce que cela ne garantit PAS

• Une PR approuvée n'est pas une PR correcte : une revue humaine rate des erreurs. Les tests sont un autre filet.
• Une CI verte prouve que les vérifications prévues passent, pas qu'il n'existe aucun bogue.
• Ouvrir une PR ne donne aucun droit à ce qu'elle soit acceptée ni à une réponse rapide : les mainteneurs sont souvent bénévoles.

À retenir

Fork, branche dédiée, PR petite et claire, réponses aux revues sur la même branche, fork tenu à jour. Une revue est un échange sur le code.

Le problème

Un étudiant motivé veut contribuer à un grand dépôt de protocole. Il ouvre dix PR le premier jour pour « reformater le code ». Elles sont toutes fermées. Pourquoi ? Parce qu'il n'a ni lu les règles ni demandé ce dont le projet avait besoin. La contribution est une relation autant qu'un code.

Par où commencer

Les dépôts de grands protocoles sont publics, par exemple ceux de Polkadot SDK ou de Cosmos SDK. Les premières contributions raisonnables sont modestes :

• Corriger une faute de documentation ou un lien mort.
• Améliorer ou traduire un guide (si le projet accepte les traductions).
• Reproduire un bogue signalé et écrire un cas de test.
• Prendre un ticket marqué pour les débutants (souvent « good first issue »), après avoir commenté que vous le prenez, pour éviter que deux personnes fassent la même chose.

Avant de proposer quoi que ce soit : lisez README, CONTRIBUTING, le code de conduite, la licence. La licence dit à quelles conditions votre contribution est publiée et réutilisée ; en contribuant, vous acceptez en général qu'elle le soit sous la licence du projet. N'envoyez jamais de code que vous n'avez pas le droit de publier (code d'un employeur, copié sans licence adaptée).

Restez bref et précis dans une demande d'aide : version de l'outil, commande lancée, message d'erreur complet, ce que vous avez déjà essayé.

Prouver qui a écrit un commit

Le nom et l'e-mail d'un commit s'écrivent librement ; n'importe qui peut en mettre un faux. Pour qu'un commit soit lié à une clé, Git permet de le signer (git commit -S, avec une clé GPG ou, dans les versions récentes, une clé SSH). GitHub affiche alors « Verified » si la signature correspond à une clé enregistrée sur votre compte et si l'adresse e-mail du commit est une adresse vérifiée de ce compte. La signature prouve que le détenteur de la clé a créé le commit ; elle ne prouve pas que le contenu est bon (retour sur l'atelier consacré aux signatures).

Le secret poussé par erreur

Scénario : Aïssatou travaille sur un dépôt public. Elle ajoute un fichier .env qui contient une clé d'API de test et le pousse. Dix minutes plus tard, elle s'en aperçoit, supprime le fichier et pousse un nouveau commit. Est-ce réglé ? Non.

Pourquoi supprimer ne suffit jamais :

• Le fichier reste dans le commit précédent, donc dans l'historique que n'importe qui peut cloner.
• Des programmes parcourent en continu les dépôts publics à la recherche de clés ; une clé publiée peut être trouvée très vite. Dites-vous qu'elle est déjà copiée.
• Des forks, des clones et des caches peuvent avoir conservé la version.
• Même si vous réécrivez l'historique et forcez le push, les copies déjà faites existent toujours.

Ordre d'action correct :

1. Révoquer ou renouveler la clé immédiatement chez le fournisseur du service (c'est ce qui la rend inutile). Pour une clé de portefeuille de chaîne : considérer les fonds comme exposés et les déplacer vers une nouvelle clé, sans attendre.
2. Vérifier l'usage : journaux d'accès du service, activité de la clé, pour savoir si elle a servi.
3. Retirer le secret des fichiers courants et ajouter le motif au fichier .gitignore (.env). Attention : .gitignore n'agit pas sur un fichier déjà suivi par Git ; il faut aussi git rm --cached .env pour que Git cesse de le suivre.
4. Seulement ensuite, nettoyer l'historique si nécessaire (par exemple avec l'outil git filter-repo puis un push forcé, en prévenant l'équipe) : c'est de l'hygiène, pas une sécurité.
5. Prévenir la récidive : un fichier .env.example sans valeurs, un contrôle automatique des secrets avant commit ou en CI, et la fonction d'analyse des secrets de l'hébergeur (qui ne détecte que des formes connues).

Exemple chiffré du coût de l'ordre : renouveler la clé prend 5 minutes ; nettoyer l'historique et prévenir une équipe de 10 personnes prend une heure. Si l'on nettoie d'abord, la clé reste valide pendant cette heure. L'ordre n'est pas une question de goût.

Ce que cela ne garantit PAS

• Signer ses commits ne protège pas contre le vol de la clé de signature : protégez-la comme une clé SSH.
• Un outil de détection de secrets ne trouve pas tout : une clé sans motif reconnaissable passe à travers.
• Contribuer à un grand dépôt ne garantit ni une réponse, ni l'acceptation, ni un emploi : c'est une manière de montrer un travail vérifiable.

À retenir

Commencez petit, lisez les règles, demandez avant de vous lancer. Un secret poussé est un secret perdu : révoquez d'abord, nettoyez ensuite.