Infuseting
/
Skills
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
Skills/modern-git-workflow/SKILL.md

12 KiB
Raw Blame History

name description
modern-git-workflow Standard de pointe pour l'ingénierie Git : interdiction formelle de développer sur la branche par défaut, création systématique de feature branches courtes, commits atomiques conformes à Conventional Commits 1.0.0, synchronisation par rebase pré-merge anti-conflits, intégration en Squash and Merge, stashes éphémères nommés et Pull/Merge Requests multi-forges (GitHub, GitLab, Gitea).

Modern Git Engineering Workflow

Ce skill formalise les standards actuels de l'industrie logicielle pour la gestion du cycle de vie du code sous Git. Il impose une hygiène rigoureuse : développement exclusivement sur branches isolées, commits atomiques et conventionnels, synchronisation linéaire par rebase, fusion par Squash and Merge, et gestion sécurisée du stash et des Pull Requests.

🎯 Règle Cardinale : Protection de la Branche par Défaut

[!IMPORTANT] Interdiction Absolue de Développer ou Commiter sur la Branche par Défaut L'agent et le développeur ne doivent JAMAIS apporter de modifications de code directes ni effectuer de commit sur main, master, trunk ou develop.

Protocole Agent Obligatoire avant toute modification de fichier ou commit :

  1. Vérifier la branche courante : git branch --show-current
  2. Si la branche retournée est la branche par défaut (main, master, develop) :
    • Arrêt immédiat de l'opération en cours.
    • Créer et basculer sur une branche dédiée : git switch -c <type>/<nom-descriptif>
  3. Ne reprendre le travail ou les commits que sur cette branche isolée.

1. 🎯 Norme Actuelle de Référence & Spécifications Officielles

Ce workflow s'appuie sur quatre piliers normatifs majeurs de l'ingénierie logicielle contemporaine :

  1. GitHub Flow Moderne & Short-Lived Feature Branches :
    • Branches éphémères de courte durée de vie (quelques heures à 2-3 jours maximum) dérivées de main.
    • Réduction drastique des divergences de branches et des "merge hells".
  2. Spécification Conventional Commits v1.0.0 :
    • Structure sémantique standardisée : <type>(<scope optionnel>): <description en mode impératif>.
    • Compatibilité native avec le Semantic Versioning (SemVer) et la génération automatisée de changelogs.
  3. Plumbing & Porcelain Git Moderne (Git 2.23+) :
    • Abandon des usages ambigus de git checkout au profit des commandes spécialisées git switch et git restore.
    • Utilisation de git push --force-with-lease pour protéger l'historique collaboratif lors des réécritures post-rebase.
  4. Sécurité AppSec & Secrets Management (OWASP) :
    • Contrôle strict de l'index (git diff --staged) pour interdire le commit accidentel de secrets (.env, tokens, clés privées).

2. ✅ Bonnes Pratiques (Do's) vs ❌ Anti-patterns & Pièges (Don'ts)

Sujet ✅ Bonnes Pratiques (Do's) ❌ Anti-patterns & Pièges à Bannir (Don'ts)
Branche de travail Créer une branche dédiée préfixée (feat/auth-jwt, fix/cache-ttl) depuis origin/main à jour. Commiter directement sur main, master ou develop.
Messages de commit Conventional Commits : feat(api): add idempotency key check (impératif, minuscule, sans point final). Messages vagues, paresseux ou génériques : fix, wip, update, test bug.
Taille des commits Commits atomiques : une seule intention logique vérifiable avec tests passants. Méga-commits mélangeant refactorisation, correction de bug et ajout de dépendances.
Synchronisation Rebaser sur la branche cible avant merge : git fetch puis git rebase origin/main. Fusionner main dans la feature branch via git merge main (accumulation de merge commits polluants).
Push post-rebase Toujours utiliser git push --force-with-lease pour sécuriser le remote contre les écrasements. Utiliser git push --force (-f) aveugle qui écrase le travail des collaborateurs.
Stratégie de fusion Squash and Merge pour intégrer la PR sur main en 1 commit synthétique, propre et bisectionnable. Fusions sans squash créant un graphe de commits "spaghetti" et des commits WIP sur main.
Gestion du stash Nommer explicitement le stash avec -u : git stash push -u -m "wip user profile" et dépiler immédiatement (git stash pop). Empiler des git stash anonymes oubliés sans inclure les fichiers non suivis.
Hygiène de staging Examiner systématiquement git diff --staged avant de commiter pour filtrer secrets et fichiers temporaires. Exécuter aveuglément git add . ou git add -A sans inspecter l'index.

3. 📐 Architecture & Flux Étape par Étape

3.1 Cycle de Vie d'une Feature Branch (Mermaid gitGraph)

gitGraph
   commit id: "Initial commit"
   commit id: "feat: add user schema"
   branch feat/login-endpoint
   checkout feat/login-endpoint
   commit id: "feat(auth): add login controller"
   commit id: "test(auth): add unit tests for login"
   checkout main
   commit id: "fix(core): update dependencies"
   checkout feat/login-endpoint
   merge main id: "Rebase origin/main"
   checkout main
   merge feat/login-endpoint id: "Squash & Merge PR #1"
   commit id: "docs: update API documentation"

3.2 Algorithme de Contrôle Agentique (Mermaid flowchart TD)

flowchart TD
    A[Nouvelle Tâche ou Modification Demandée] --> B{Vérifier branche courante<br/>git branch --show-current}
    B -- Est main, master ou develop --> C[Alerte: Branche protégée !]
    C --> D[git switch -c type/nom-de-feature origin/main]
    D --> E[Implémentation des changements]
    B -- Est une feature branch valide --> E
    
    E --> F[Vérifications locales: Lint, Typage & Tests unitaires]
    F -- Échec --> E
    F -- Succès --> G[git diff --staged : Audit anti-secrets & fichiers temporaires]
    G --> H[Commit atomique: Conventional Commits 1.0.0]
    
    H --> I{Fin de la feature ?}
    I -- Non --> E
    I -- Oui --> J[git fetch origin main]
    J --> K[git rebase origin/main]
    K -- Conflits --> L[Résolution méthodique étape par étape]
    L --> K
    K -- Succès --> M[Tests de validation post-rebase]
    M --> N[git push --force-with-lease origin feat/...]
    N --> O[Création de la PR/MR avec template universel]
    O --> P[Validation finale ➔ Squash and Merge sur main]

4. 💻 Protocoles & Scénarios d'Exécution Guidés

4.1 Convention de Nommage des Branches

Chaque branche doit suivre le format : <type>/<nom-descriptif-en-kebab-case>

Préfixe Usage Exemple
feat/ Nouvelle fonctionnalité métier ou technique feat/oauth2-google-login
fix/ Correction d'une anomalie ou d'un bug fix/session-expiry-race-condition
refactor/ Restructuration de code sans modification de comportement refactor/database-connection-pool
chore/ Tâches de maintenance, dépendances, configuration chore/upgrade-typescript-5
docs/ Modification exclusive de la documentation docs/openapi-swagger-spec
test/ Ajout ou fiabilisation de tests automatisés test/e2e-checkout-flow
perf/ Optimisation des performances perf/cache-redis-product-list

4.2 Spécification Conventional Commits 1.0.0

Chaque commit doit respecter la structure :

<type>(<scope optionnel>): <sujet impératif en minuscules>

[Corps explicatif optionnel détaillant le POURQUOI et les arbitrages techniques]

[Références de tickets ou mention de rupture]

Règles Typographiques :

  • Sujet : Verbe à l'impératif présent (add, fix, refactor, remove), en minuscules, sans point final, 50-72 caractères max.
  • Rupture de compatibilité (Breaking Change) : Ajouter un ! après le type/scope ou un pied de page BREAKING CHANGE: <description>.
# Exemple de commit standard
git commit -m "feat(auth): add rate limiting to login endpoint"

# Exemple de commit avec breaking change
git commit -m "refactor(api)!: drop legacy v1 authentication endpoints

BREAKING CHANGE: The /v1/auth route has been removed. All clients must migrate to /v2/tokens."

4.3 Protocole de Synchronisation par Rebase (Pré-Merge Anti-Conflits)

Avant toute fusion ou ouverture finale de PR :

# 1. S'assurer que le répertoire de travail est propre
git status

# 2. Récupérer l'état le plus récent de la branche cible
git fetch origin main

# 3. Rebaser votre feature branch sur la branche cible
git rebase origin/main

# 4. En cas de conflit : consulter le guide de résolution
#    (voir references/conflict-resolution.md)

# 5. Relancer la suite de tests pour valider l'intégrité
npm test # ou pytest, cargo test, etc.

# 6. Pousser avec sécurité anti-écrasement
git push --force-with-lease origin feat/votre-feature

4.4 Stratégie de Fusion Finale : Squash and Merge

La stratégie d'intégration standardisée est le Squash and Merge :

  • Pourquoi ? Il condense l'ensemble des commits intermédiaires d'une feature branch en un seul commit atomique, propre et parfait sur la branche main.
  • Avantages majeurs :
    • Historique de main 100% linéaire et limpide.
    • Facilité de retour arrière immédiat (git revert <commit_sha>).
    • Efficacité absolue de git bisect pour détecter une régression sans tomber sur des commits intermédiaires cassés.

4.5 Protocole Stash Éphémère & Sécurisé

Le stash est un tampon volatile à courte durée de vie. Ne jamais laisser de stashes anonymes orphelins.

# 1. Sauvegarder l'état en cours en incluant les nouveaux fichiers (-u) avec un motif clair
git stash push -u -m "wip: tentative refactorisation token service"

# 2. Effectuer l'opération urgente (ex: bascule de branche, pull urgent)
git switch fix/urgent-bug

# 3. De retour sur la branche, vérifier le stash
git stash list

# 4. Réappliquer immédiatement et dépiler
git stash pop

# En cas d'alternative pour du travail parallèle lourd : privilégier `git worktree`
# (voir references/git-commands-cheat-sheet.md)

4.6 Pull Requests & Merge Requests Multi-Forges

Le skill prend en charge toutes les forges logicielles courantes :

  1. Détection du remote : git remote get-url origin
  2. Si GitHub et gh installé : 
    gh pr create --base main --head <branche> --title "<type>(<scope>): <titre>" --body "..."
  3. Si GitLab et glab installé : 
    glab mr create --target-branch main --source-branch <branche> --title "<type>(<scope>): <titre>"
  4. Pour Gitea ou toute interface web : Utiliser systématiquement le Gabarit Universel de Pull Request.

5. 📋 Checklist de Conformité & Références Officielles

Checklist de l'Agent avant Clôture d'une Tâche Git :

  • Le travail a été réalisé sur une branche dédiée (jamais sur main/master/develop).
  • Le nom de la branche respecte la taxonomie (feat/..., fix/..., etc.).
  • Chaque commit suit la norme Conventional Commits 1.0.0.
  • Aucun secret, mot de passe, clé d'API ou token n'a été indexé.
  • Les tests automatisés et linters s'exécutent avec succès en local.
  • La branche a été rebasée sur origin/main sans conflit résiduel.
  • Le push a été réalisé avec --force-with-lease (jamais de --force brut).
  • La description de la PR / MR respecte le gabarit universel avec plan de test documenté.

Références & Documentation Associée