---
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.