# 📋 Guide de travail — GitHub Projects

> Ce document explique comment nous organisons le travail dans GitHub pour le développement de l'application. Il sert de guide d'onboarding pour toute nouvelle personne qui rejoint le projet.

---

## Table des matières

1. [Objectif de notre organisation](#1-objectif-de-notre-organisation)
2. [Vue d'ensemble du workflow](#2-vue-densemble-du-workflow)
3. [Tout commence par une issue](#3-tout-commence-par-une-issue)
4. [Les status du projet](#4-les-status-du-projet)
5. [Les priorités](#5-les-priorités)
6. [Les versions](#6-les-versions)
7. [Les labels](#7-les-labels)
8. [Les milestones](#8-les-milestones)
9. [Créer une bonne issue](#9-créer-une-bonne-issue)
10. [Template — Bug issue](#10-template--bug-issue)
11. [Template — Feature issue](#11-template--feature-issue)
12. [Règles de triage](#12-règles-de-triage)
13. [Règles de développement](#13-règles-de-développement)
14. [Gérer les bugs](#14-gérer-les-bugs)
15. [Features de la version 0](#15-features-de-la-version-0)
16. [Choisir entre v0.0, v0.1, v0.2 et v1.0](#16-choisir-entre-v00-v01-v02-et-v10)
17. [Exemples complets](#17-exemples-complets)
18. [Fermer une issue](#18-fermer-une-issue)
19. [Tickets bloqués](#19-tickets-bloqués)
20. [Routine recommandée](#20-routine-recommandée)
21. [Bonnes pratiques](#21-bonnes-pratiques)
22. [Résumé pour un nouveau membre](#22-résumé-pour-un-nouveau-membre)
23. [Convention finale](#23-convention-finale)

---

## 1. Objectif de notre organisation

Nous utilisons GitHub pour centraliser le code, les tickets, les bugs, les fonctionnalités à développer et le suivi des versions. Notre objectif est de garder une organisation **simple, lisible et efficace** pour une petite équipe.

Nous voulons pouvoir répondre rapidement à ces questions :

- ✅ Qu'est-ce qui est à faire maintenant ?
- 🐛 Quels bugs bloquent la version actuelle ?
- 🚀 Quelles fonctionnalités font partie de la version 0 ?
- 💡 Quelles idées doivent attendre une prochaine version ?
- 👤 Qui travaille sur quoi ?
- 🔄 Qu'est-ce qui est terminé, bloqué ou en revue ?

L'organisation repose sur **cinq éléments principaux** :

| # | Élément | Rôle |
|---|---------|------|
| 1 | **Status** | L'état d'avancement d'un ticket dans le board |
| 2 | **Priority** | L'importance du ticket |
| 3 | **Version** | La version cible ou le contexte du ticket |
| 4 | **Labels** | La nature du ticket : bug, feature, design, etc. |
| 5 | **Milestones** | Les grandes étapes de livraison |

---

## 2. Vue d'ensemble du workflow

Tout travail doit être représenté par une **GitHub Issue**. Une issue peut représenter :

- un bug à corriger
- une nouvelle fonctionnalité
- une amélioration
- une tâche de design ou de documentation
- une dette technique
- une décision d'architecture

### Cycle de vie d'une issue

```
Inbox → Backlog → Todo → In Progress → In Review → Done
                                    ↘
                                    Blocked
```

> **Principe clé :** Ne jamais perdre une idée ou un bug, mais ne pas mélanger les idées futures avec le travail prioritaire de la version actuelle.

---

## 3. Tout commence par une issue

Avant de développer une fonctionnalité ou corriger un bug, il faut **créer ou utiliser une issue existante**.

Une bonne issue doit contenir :

- [ ] Un titre clair
- [ ] Une description compréhensible
- [ ] Un label adapté
- [ ] Une priorité
- [ ] Un status
- [ ] Une version cible
- [ ] Une milestone si planifiée pour une livraison

### Exemples de titres

| ✅ Bon titre | ❌ Mauvais titre |
|-------------|----------------|
| `Add password reset flow` | `password` |
| `Fix login crash on special characters` | `bug` |
| `Improve dashboard empty state` | `fix` |

---

## 4. Les status du projet

| Status | Signification | Quand l'utiliser |
|--------|--------------|-----------------|
| 📥 **Inbox** | Nouvelle idée ou bug non trié | Ticket créé mais pas encore analysé |
| 📋 **Backlog** | Travail à faire plus tard | Ticket valide mais pas encore prioritaire |
| 📌 **Todo** | Travail non commencé | Ticket prêt à être développé |
| ⚙️ **In Progress** | Travail en cours | Une personne travaille activement dessus |
| 👀 **In Review** | Revue ou test en cours | PR ouverte ou ticket en validation |
| 🚫 **Blocked** | Bloqué | Dépendance, décision ou problème bloquant |
| ✅ **Done** | Terminé | Travail terminé, mergé et validé |

### Détail des status

#### 📥 Inbox
Pour tout ce qui arrive sans analyse complète : bug signalé rapidement, idée ajoutée en discussion, demande produit encore floue. **Un ticket ne doit pas rester longtemps en Inbox.**

#### 📋 Backlog
Pour les tickets valides mais non planifiés immédiatement : fonctionnalité pour plus tard, amélioration non urgente, idée pour la v1.

#### 📌 Todo
Le ticket doit être suffisamment clair pour qu'un développeur puisse commencer **sans redéfinir le besoin**.

#### ⚙️ In Progress
> ⚠️ **Règle recommandée :** Maximum **1 ou 2 tickets** en In Progress par personne.

#### 👀 In Review
Quand une PR est ouverte, que le code attend une revue, ou que la fonctionnalité attend un test.

#### 🚫 Blocked
L'issue doit expliquer clairement **ce qui bloque** dans un commentaire (décision manquante, dépendance externe, etc.).

#### ✅ Done
Code mergé + fonctionnalité testée + documentation à jour + aucune action restante.

---

## 5. Les priorités

| Priority | Signification | Exemple |
|----------|--------------|---------|
| 🔴 **Critical** | Bloque l'application ou la livraison | Login impossible, crash majeur, perte de données |
| 🟠 **High** | Important pour la version actuelle | Feature indispensable à la v0, bug important |
| 🟡 **Medium** | Utile mais non bloquant | Amélioration UX, feature secondaire |
| 🟢 **Low** | Peut attendre | Idée future, optimisation non urgente |

### Quand utiliser Critical ?

Uniquement quand :
- L'application ne démarre pas
- L'utilisateur ne peut pas se connecter
- Une fonctionnalité essentielle de la v0 ne fonctionne pas
- Une action provoque une perte de données
- Le déploiement est cassé

---

## 6. Les versions

| Version | Signification |
|---------|--------------|
| `dev` | Travail technique interne non lié à une release publique |
| `v0.0` | Première version minimale utilisable |
| `v0.1` | Stabilisation après les premiers tests |
| `v0.2` | Complément fonctionnel de la version 0 |
| `v1.0` | Prochaine version majeure après validation de la v0 |

### Guide de décision

```
Sans cette tâche, l'application n'est pas utilisable ?  → v0.0
Stabilise l'expérience après premiers tests ?           → v0.1
Complète la v0 mais non indispensable au MVP ?          → v0.2
Évolution majeure ou future ?                           → v1.0
Tâche purement technique/interne ?                      → dev
```

---

## 7. Les labels

| Label | Signification | Quand l'utiliser |
|-------|--------------|-----------------|
| `Architecture` | Décision ou travail d'architecture | Structure technique, choix de stack |
| `bug` | Quelque chose ne fonctionne pas | Erreur, crash, comportement inattendu |
| `design` | UI/UX, maquettes, parcours | Design écran, flow utilisateur |
| `documentation` | Documentation | README, guide technique |
| `feature` | Nouvelle fonctionnalité | Nouvelle capacité utilisateur |
| `improvement` | Amélioration d'une fonctionnalité existante | Optimisation, meilleur comportement |
| `tech-debt` | Dette technique | Refactor, nettoyage, maintenance |

### `feature` vs `improvement`

- **`feature`** → On ajoute quelque chose de nouveau  
  Exemple : `Add password reset flow`
- **`improvement`** → On améliore quelque chose qui existe  
  Exemple : `Improve validation messages on login form`

### `bug` vs `improvement`

- **`bug`** → Le comportement actuel est **incorrect**
- **`improvement`** → Le comportement fonctionne, mais peut être **meilleur**

---

## 8. Les milestones

| Milestone | Objectif |
|-----------|---------|
| `v0.0 — MVP usable` | Première version fonctionnelle de bout en bout |
| `v0.1 — Stabilisation` | Corriger les retours initiaux, stabiliser l'UX |
| `v0.2 — Feature completion` | Compléter les features prévues en v0 |
| `v1.0 — Next version` | Préparer les fonctionnalités majeures suivantes |

### Version vs Milestone

| Champ | Usage |
|-------|-------|
| **Version** | Filtrer et organiser le board |
| **Milestone** | Suivre l'avancement d'une release avec progression |

> Une idée future peut avoir une **Version** mais pas encore de **Milestone**.

---

## 9. Créer une bonne issue

### Étape 1 — Titre clair

Le titre doit commencer par une action ou décrire précisément le problème.

```
✅ Fix login error when password contains special characters
✅ Add password reset flow
✅ Improve dashboard empty state
✅ Create architecture document for authentication module

❌ bug
❌ login
❌ fix
❌ new feature
```

### Étape 2 — Description

Une bonne description contient :
- Le **contexte**
- Le **problème** ou le besoin
- Le **résultat attendu**
- Les **critères d'acceptation**
- Les **informations techniques** utiles

### Étape 3 — Champs obligatoires

Chaque issue doit avoir au minimum :

```
Status    → obligatoire
Priority  → obligatoire
Version   → obligatoire
Label     → obligatoire
Milestone → si planifiée dans une release
```

---

## 10. Template — Bug issue

```markdown
## Description
Décrire le bug clairement.

## Étapes pour reproduire
1. 
2. 
3. 

## Résultat actuel
Ce qui se passe actuellement.

## Résultat attendu
Ce qui devrait se passer.

## Impact
Expliquer l'impact sur l'utilisateur ou sur la version en cours.

## Environnement
- Navigateur : 
- OS : 
- Version : 
- Compte de test : 

## Screenshots / logs
Ajouter captures, logs ou informations utiles.
```

**Classification recommandée :**

| Champ | Valeur typique |
|-------|---------------|
| Label | `bug` |
| Priority | Critical / High / Medium / Low selon l'impact |
| Version | dev / v0.0 / v0.1 / v0.2 / v1.0 |
| Status | `Inbox` au départ, puis `Todo` quand confirmé |
| Milestone | La release dans laquelle le bug doit être corrigé |

---

## 11. Template — Feature issue

```markdown
## Objectif
Quel problème utilisateur cette fonctionnalité résout-elle ?

## Description
Décrire la fonctionnalité attendue.

## Critères d'acceptation
- [ ] Critère 1
- [ ] Critère 2
- [ ] Critère 3

## Priorité produit
Pourquoi cette fonctionnalité est importante maintenant ou plus tard ?

## Notes techniques
Architecture, API, base de données, contraintes, dépendances.

## Design / UX
Lien vers maquette ou description du parcours utilisateur.
```

**Classification recommandée :**

| Champ | Valeur typique |
|-------|---------------|
| Label | `feature` |
| Priority | High si indispensable, Medium ou Low sinon |
| Version | v0.0 / v0.1 / v0.2 / v1.0 |
| Status | `Backlog` ou `Todo` |
| Milestone | La release prévue |

---

## 12. Règles de triage

À faire **régulièrement** (chaque semaine) :

1. Ouvrir les issues en **Inbox**
2. Vérifier si la description est claire
3. Ajouter ou corriger le **label**
4. Définir la **priorité**
5. Définir la **version**
6. Ajouter une **milestone** si planifiée
7. Déplacer vers **Backlog** ou **Todo**

### Règle simple

```
Ticket pas clair         → reste en Inbox
Ticket clair, non urgent → Backlog
Ticket clair, prêt       → Todo
```

---

## 13. Règles de développement

### Avant de commencer

Vérifier que :
- [ ] Le besoin est clair
- [ ] Les critères d'acceptation sont définis
- [ ] La priorité et la version sont correctes
- [ ] La milestone est définie si planifiée
- [ ] Il n'y a pas de dépendance bloquante

### Pendant le développement

1. **S'assigner** l'issue
2. Passer le status en **In Progress**
3. **Créer une branche** liée à l'issue

**Format des branches :**

```
feature/issue-number-short-description
fix/issue-number-short-description
improvement/issue-number-short-description
tech/issue-number-short-description
```

**Exemples :**

```
feature/12-password-reset
fix/18-login-special-characters
improvement/25-dashboard-empty-state
tech/31-auth-refactor
```

### Pull Request

- Lier la PR à l'issue
- Ajouter une description claire (ce qui a été fait + comment tester)
- Passer l'issue en **In Review**
- Utiliser `Closes #12` pour fermer automatiquement l'issue au merge

### Après le merge

1. Vérifier que l'issue est fermée
2. Passer le status en **Done**
3. Vérifier l'avancement de la milestone

---

## 14. Gérer les bugs

| Priorité | Critères |
|----------|---------|
| 🔴 **Critical** | Application bloquée, parcours principal inaccessible, perte de données, déploiement impossible |
| 🟠 **High** | Gêne fortement l'utilisation, touche une fonctionnalité importante, à corriger avant la prochaine release |
| 🟡 **Medium** | Contournement possible, impact limité, ne bloque pas la v0 |
| 🟢 **Low** | Bug mineur ou visuel, ne gêne pas réellement l'utilisation |

> Les bugs **Critical** doivent être traités **avant** les nouvelles features.

---

## 15. Features de la version 0

La version 0 doit rester concentrée sur l'essentiel. Pour chaque feature, poser la question :

> **Est-ce que cette fonctionnalité est indispensable pour qu'un premier utilisateur teste correctement l'application ?**

```
Oui, indispensable                     → v0.0
Utile rapidement, pas indispensable    → v0.1
Dans la vision v0, peut attendre       → v0.2
Ambitieuse ou non nécessaire pour v0   → v1.0
```

---

## 16. Choisir entre v0.0, v0.1, v0.2 et v1.0

| Question | Version recommandée |
|----------|-------------------|
| Sans cette tâche, l'application n'est pas utilisable de bout en bout ? | `v0.0` |
| Cette tâche corrige ou stabilise l'expérience après premiers tests ? | `v0.1` |
| Cette tâche complète la v0 mais n'est pas indispensable au MVP ? | `v0.2` |
| Cette tâche est une évolution majeure ou future ? | `v1.0` |
| Cette tâche est purement technique/interne ? | `dev` |

---

## 17. Exemples complets

### Exemple 1 — Bug bloquant

```
Title:     Fix login crash when password contains special characters
Label:     bug
Priority:  Critical
Version:   v0.0
Milestone: v0.0 — MVP usable
Status:    Todo
```
> Ce bug bloque un parcours essentiel. Il doit être corrigé avant la première version utilisable.

---

### Exemple 2 — Feature indispensable v0

```
Title:     Add user registration flow
Label:     feature
Priority:  High
Version:   v0.0
Milestone: v0.0 — MVP usable
Status:    Todo
```
> L'inscription est nécessaire pour que l'application soit utilisable.

---

### Exemple 3 — Amélioration après premiers tests

```
Title:     Improve error messages on login form
Label:     improvement
Priority:  Medium
Version:   v0.1
Milestone: v0.1 — Stabilisation
Status:    Backlog
```
> L'application peut fonctionner sans cette amélioration, mais elle améliore l'UX.

---

### Exemple 4 — Feature non urgente

```
Title:     Add advanced notification preferences
Label:     feature
Priority:  Medium
Version:   v0.2
Milestone: v0.2 — Feature completion
Status:    Backlog
```

---

### Exemple 5 — Idée pour v1

```
Title:     Add AI-based recommendations
Label:     feature
Priority:  Low
Version:   v1.0
Milestone: v1.0 — Next version
Status:    Backlog
```

---

### Exemple 6 — Dette technique

```
Title:     Refactor authentication service
Label:     tech-debt
Priority:  Medium
Version:   dev
Milestone: aucune
Status:    Backlog
```

---

## 18. Fermer une issue

Une issue peut être mise en **Done** seulement si :

- [ ] Le travail demandé est terminé
- [ ] La PR est mergée (si du code était nécessaire)
- [ ] Les critères d'acceptation sont respectés
- [ ] Les tests ont été faits
- [ ] Aucun point bloquant n'est encore ouvert
- [ ] La documentation est mise à jour si nécessaire

> ⚠️ Ne pas mettre une issue en Done simplement parce que le développement a commencé ou qu'une PR est ouverte.

---

## 19. Tickets bloqués

Quand une issue est mise en **Blocked**, ajouter un commentaire qui explique :

- Ce qui bloque
- Qui peut débloquer
- Quelle décision ou action est attendue
- Depuis quand le blocage existe

**Exemple de commentaire :**

```
Blocked because the API contract for user roles is not decided yet.
Need decision from the backend owner before implementation can continue.
```

> Une issue bloquée doit être **revue régulièrement**.

---

## 20. Routine recommandée

### Chaque jour / session de développement

1. Ouvrir le board GitHub Projects
2. Regarder les tickets **Critical** et **High**
3. Vérifier les tickets **Blocked**
4. Choisir un ticket **Todo** clair
5. Le passer en **In Progress**
6. Créer une branche
7. Ouvrir une PR quand le travail est prêt
8. Passer en **In Review**
9. Passer en **Done** après validation et merge

### Chaque semaine

1. Revoir les tickets en **Inbox**
2. Nettoyer le **Backlog**
3. Vérifier que les priorités sont encore correctes
4. Vérifier l'avancement des milestones
5. Déplacer les idées non essentielles vers **v1.0**

---

## 21. Bonnes pratiques

### 🎯 Garder la v0 simple
La v0 doit valider que l'application fonctionne et apporte de la valeur — pas contenir toutes les idées possibles.

### 🔍 Ne pas mélanger bug et feature
- **Bug** → corrige un comportement incorrect
- **Feature** → ajoute un nouveau comportement

### ⚡ Ne pas surcharger In Progress
Trop de tickets en cours signifie souvent que rien n'avance vraiment jusqu'au bout. Limite : **1 à 2 tickets max par personne**.

### 🔗 Toujours lier issue et PR
Chaque PR doit idéalement être liée à une issue via `Closes #N`.

### 📊 Utiliser les milestones pour suivre les releases
Les milestones permettent de voir rapidement combien de tickets restent ouverts et si une release est proche.

---

## 22. Résumé pour un nouveau membre

Quand tu rejoins le projet :

1. 📖 Lis ce document
2. 🔍 Ouvre le GitHub Project
3. 👀 Regarde les colonnes du board
4. 🎯 Regarde d'abord les tickets **Todo** avec priorité **Critical** ou **High**
5. ❓ Ne commence pas un ticket flou — demande clarification ou laisse-le en Inbox
6. 👤 Quand tu commences, assigne-toi l'issue et passe-la en **In Progress**
7. 🌿 Crée une branche avec le numéro de l'issue
8. 🔗 Ouvre une PR liée à l'issue
9. 👀 Passe l'issue en **In Review**
10. ✅ Après merge et validation, passe l'issue en **Done**

---

## 23. Convention finale

Pour chaque issue, respecter cette structure minimale :

```
Title:     Clair et actionnable
Label:     bug / feature / improvement / design / documentation / tech-debt / Architecture
Priority:  Critical / High / Medium / Low
Version:   dev / v0.0 / v0.1 / v0.2 / v1.0
Status:    Inbox / Backlog / Todo / In Progress / In Review / Blocked / Done
Milestone: Uniquement si la tâche est planifiée dans une release
```

---

*Cette convention permet à toute l'équipe de comprendre rapidement l'état du projet et de travailler de manière cohérente.*