259 lines
12 KiB
Markdown
259 lines
12 KiB
Markdown
---
|
|
name: modern-git-workflow
|
|
description: >-
|
|
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`)
|
|
|
|
```mermaid
|
|
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`)
|
|
|
|
```mermaid
|
|
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 :
|
|
```text
|
|
<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>`.
|
|
|
|
```bash
|
|
# 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 :
|
|
|
|
```bash
|
|
# 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.
|
|
|
|
```bash
|
|
# 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é** :
|
|
```bash
|
|
gh pr create --base main --head <branche> --title "<type>(<scope>): <titre>" --body "..."
|
|
```
|
|
3. **Si GitLab et `glab` installé** :
|
|
```bash
|
|
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](./references/pr-templates.md).
|
|
|
|
---
|
|
|
|
## 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
|
|
|
|
- **[Gabarits Universels de PR & MR](./references/pr-templates.md)** : Modèles complets pour GitHub, GitLab et Gitea.
|
|
- **[Guide de Résolution de Conflits](./references/conflict-resolution.md)** : Procédure pas à pas en 5 étapes lors du rebase.
|
|
- **[Aide-Mémoire des Commandes Git Modernes](./references/git-commands-cheat-sheet.md)** : Référence rapide des commandes `switch`, `restore`, `stash push -u`, `worktree`.
|
|
- **[Spécification Conventional Commits 1.0.0](https://www.conventionalcommits.org/en/v1.0.0/)** : Standard officiel des messages de commit.
|
|
- **[Git Documentation Officielle](https://git-scm.com/doc)** : Documentation de référence du moteur Git.
|
|
- **[OWASP Secrets Management Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Secrets_Management_Cheat_Sheet.html)** : Bonnes pratiques de prévention des fuites de données d'authentification dans le code source.
|