Workflow de collaboration¶


Auteur	Christophe
Date	2026-03-17
Destinataire(s)	Toute l'equipe
Sujet	Workflow GitHub complet : Epics, Stories, PRs, review, collaboration cross-repo

1. Vue d'ensemble¶

L'organisation utilise un seul GitHub Project (Projects v2) partage entre tous les repos. Toutes les issues de tous les repos y sont centralisees, ce qui donne une vision unifiee du travail en cours.

Statuts des stories¶

Le board utilise les statuts suivants pour les stories :

Backlog → Ready → In Progress → In Review → Done

Transition	Condition
Backlog → Ready	Enablers Done + story estimee + titre conforme + template rempli
Ready → In Progress	Un dev s'auto-assigne
In Progress → In Review	PR ouverte
In Review → Done	PR mergee, issue fermee automatiquement

Statuts des Epics¶

Les Epics ne suivent pas ce workflow. Elles restent en No Status tant qu'elles sont en cours, et passent directement a Finish une fois toutes leurs stories terminees et tous les Completion Criteria coches. Elles ne passent jamais par Backlog, Ready, In Progress, etc. — elles servent uniquement de conteneur pour regrouper les stories liees.

2. Epics¶

Role¶

Une Epic est un grand objectif (metier ou technique) qui s'etend sur plusieurs sprints. Elle n'est jamais assignee a une personne et n'apparait pas sur le Sprint Board. Elle est visible uniquement dans les vues Roadmap et Epics.

Les stories sont liees aux Epics via le mecanisme de sub-issues natif de GitHub (relation parent-enfant).

Template¶

Les sections obligatoires sont marquees d'un *.

## Description *

[Description du grand objectif. Ce que cette Epic vise a livrer,
le contexte, le livrable cible.]

## Cross-Cutting Conventions

[Conventions qui s'appliquent a TOUTES les stories de l'Epic.
Par exemple : patterns d'erreurs a utiliser, regles de sanitizers,
conventions de logging, etc.
Cette section evite de repeter les memes contraintes dans chaque story.]

## Structure *

[Vue d'ensemble des enablers et stories, avec estimation relative.]

    Epic: Nom (vX.Y.Z)
    |
    +-- Enabler 1: Nom (N stories)     [S M L ...]
    +-- Enabler 2: Nom (N stories)     [M M S ...]
    ...
    Sizing: S = 1-2 jours, M = 2-4 jours, L = 4-7 jours

## Enabler N — Nom de l'enabler *

[Pour chaque enabler, une checklist de stories avec leur numero
d'issue, leur titre court, et leur taille estimee.]

- [ ] #NNN — **N.N** Titre de la story `[S]`
- [ ] #NNN — **N.N** Titre de la story `[M]`
...

## Dependency Chain *

[Graphe visuel des dependances entre stories : chemin critique et
branches parallelisables. Permet de voir quel travail peut avancer
en parallele et quels sont les goulots d'etranglement.]

## Module Mapping

[Optionnel. Mapping entre les stories et les fichiers/modules du
codebase. Utile pour les Epics techniques.]

## Completion Criteria *

[Checklist des criteres qui doivent TOUS etre valides pour que
l'Epic soit consideree comme terminee. Cocher au fur et a mesure.]

- [ ] Critere 1
- [ ] Critere 2
...

## Out of Scope

[Optionnel mais recommande. Ce qui ne fait PAS partie de cette Epic,
pour eviter le scope creep. Indiquer dans quelle phase future ces
elements seront traites.]

Exemple : Epic #184 — `Feat(MemTideCore): Daemon foundations`¶

Cette Epic illustre bien le template :

Description : livrer les fondations du daemon C++23 (monitoring memoire, DAMON, metriques Prometheus).
Cross-Cutting Conventions : 5 conventions communes (error handling avec TExpected<T>, sanitizers ASan/TSan/UBSan, registry Prometheus, logging transitoire, capabilities Linux).
Structure : 5 enablers, 19 stories au total, avec taille relative (S/M/L).
Enablers 1 a 5 : checklists de stories avec references #NNN, cochees au fur et a mesure de leur completion.
Dependency Chain : graphe ASCII montrant le chemin critique et les branches parallelisables.
Module Mapping : correspondance story → fichier C++ (Error.hpp ← #203, etc.).
Completion Criteria : 10 criteres factuels (daemon demarre, tests passent, CI green, etc.).
Out of Scope : tableau des composants reportes a v0.3.0+.

Cycle de vie¶

Creation (No Status) → Stories completees une par une →
Toutes les stories Done + Completion Criteria coches → Finish

3. Stories¶

Role¶

Une Story est un besoin utilisateur ou technique, livrable en 1 sprint maximum (≤ 13 story points). Elle est assignee a 1 personne. Si elle necessite 2+ personnes en parallele, c'est un Epic — la decouper.

Les taches techniques d'une story sont de simples checkboxes Markdown dans le body, jamais des issues separees.

Template¶

Les sections obligatoires sont marquees d'un *.

## User Story *

As a [role],
I want [action],
so that [benefit].

**Epic**: #NNN — Titre de l'Epic
**Enabler**: N — Nom de l'enabler
**Story ID**: N.N
**Size**: S/M/L

## Description *

[Description technique detaillee de ce qui doit etre implemente.
Design, principes, choix d'architecture. Peut contenir des tableaux
de types/fonctions, des diagrammes, des rationales de design.
Cette section est le coeur de la specification.]

## Tasks *

[Checklist des taches concretes. Cocher au fur et a mesure
du developpement.]

- [ ] Implementer X
- [ ] Implementer Y
- [ ] Ecrire les tests unitaires pour X
- [ ] Ecrire les tests unitaires pour Y
...

## Affected Files *

[Liste des fichiers crees ou modifies, avec indication (create)
ou (modify). Permet au reviewer de savoir exactement quels
fichiers regarder.]

- `Path/To/File.hpp` (create)
- `Path/To/Existing.cpp` (modify)
...

## Enablers

[Si applicable. Checkboxes des issues qui doivent etre Done
avant que cette story puisse commencer.]

- [x] #NNN — Titre de l'enabler (Done)
- [ ] #NNN — Titre de l'enabler (en cours)

## Unblocks

[Optionnel. Liste des issues que cette story debloque
une fois terminee.]

- #NNN (Titre — utilise le resultat de cette story)

## Acceptance Criteria *

[Checklists detaillees, organisees par categorie, qui definissent
objectivement quand la story est "Done". Cocher au fur et a mesure.]

### Categorie A
- [ ] Critere 1
- [ ] Critere 2

### Tests
- [ ] Tests unitaires pour X
- [ ] ASan + TSan + UBSan clean

Exemple : Story #203 — `Feat(MemTideCore): Add core architecture foundations with error types and IModule interface`¶

User Story : "As a developer, I want foundational cross-cutting types established from day one, so that all subsequent stories build on a consistent architecture."
Description : specification complete de FError, TExpected<T>, IModule avec tableaux de types, design rationale, tailles memoire.
Tasks : 17 checkboxes couvrant implementation + tests + documentation.
Affected Files : 16 fichiers listes avec (create)/(modify).
Enablers : aucun (point de depart de l'Epic).
Unblocks : 4 stories listees (#185, #186, #189, #192).
Acceptance Criteria : 30+ criteres organises en 9 categories (FError core, errno, truncation, debug guard, helpers, naming, monadic chaining, IModule, tests).

L'issue est un document vivant¶

Au debut, on n'aura pas forcement tous les details pour remplir le template integralement. Cela ne doit pas empecher la creation de l'issue. L'important est de reflechir a la fonctionnalite, d'etudier comment la realiser, d'ecrire ses specs — avant de commencer a coder.

L'issue doit evoluer tout au long du developpement :

Creation : au minimum ## User Story, ## Description (meme partielle), et ## Tasks (meme grossiere).
Avant developpement : ## Affected Files, ## Enablers, ## Acceptance Criteria completes. L'issue est prete pour passer en Ready.
Pendant le developpement : les checkboxes de ## Tasks et ## Acceptance Criteria sont cochees au fur et a mesure.
Fin : toutes les checkboxes sont cochees, le template est complet, l'issue est prete a etre fermee par la PR.

Cycle de vie d'une Story¶

1. Creation (Backlog)
   → Issue creee, template partiellement rempli.

2. Refinement (Backlog → Ready)
   → Template complete, enablers verifies, estimation faite.
   → Titre au format <Type>(<Context>): <ShortMessage>.

3. Developpement (Ready → In Progress)
   → Un dev s'auto-assigne et cree sa branche.

4. PR (In Progress → In Review)
   → Le dev lance `mem pr` pour creer la PR liee.

5. Review + Merge (In Review → Done)
   → 2 approbations, PR mergee, issue fermee automatiquement.

4. Labels¶

Chaque issue doit avoir 1 label type (bleu) + 1 ou plusieurs labels domaine (vert).

Type (bleu — 1 obligatoire)¶

Label	Usage
`epic`	Conteneur de stories, plusieurs sprints
`story`	User story estimee en points, livrable en 1 sprint
`task`	Decoupage technique d'une story
`bug`	Quelque chose ne marche pas
`spike`	Investigation timeboxee (livrable = savoir, pas du code)

Domaine (vert — 1+ obligatoire)¶

Label	Usage
`build`	Systeme de build (CMake, Nix, npm)
`ci`	Pipelines CI/CD
`devex`	Experience developpeur, outillage
`packaging`	Packaging, distribution
`signals`	eBPF, DAMON, monitoring memoire
`engine`	Moteur de decision, scoring, risque
`execution`	Migration de pages, `move_pages()`
`config`	Configuration, YAML, reload
`metrics`	Prometheus, observabilite
`security`	Securite, capabilities, sandboxing

Labels speciaux¶

Label	Usage
`enabler`	Cette issue debloque d'autres issues — a prioriser
`blocked`	Cette issue a des enablers non-Done — ne peut pas etre commencee
`needs-refinement`	Story pas assez claire pour etre estimee
`good-first-issue`	Accessible pour un nouveau contributeur

Ne jamais utiliser de labels pour

La priorite, les story points, ou le sprint — utiliser les champs du GitHub Project a la place (Priority, Story Points, Iteration).

5. Branches et Pull Requests¶

Nommage des branches¶

Format : <type>/<issue-num>-<description-courte>

epic/184-daemon-foundations         ← branche d'integration Epic
feat/203-core-architecture          ← story sous un Epic → creee depuis epic/184-...
feat/89-standalone-feature          ← story sans Epic → creee depuis dev
fix/142-crash-on-startup            ← bug fix

Les story branches ciblent leur branche Epic parente si elle existe, sinon dev. Les branches Epic ciblent dev.

`mem pr` — creer et mettre a jour une PR¶

La commande mem pr s'execute depuis la branche de la story. Elle :

Detecte l'issue liee a la branche courante (via le numero dans le nom de branche).
Detecte la branche cible (branche Epic parente via les sub-issues GitHub, ou dev par defaut).
Genere le titre et le body de la PR a partir des informations de l'issue.
Cree la PR (ou la met a jour si elle existe deja — la commande est idempotente).

Cela garantit la coherence entre l'issue et la PR, et evite la duplication d'informations.

Regle cle : 1 story = 1 PR¶

Chaque issue de type story donne lieu a exactement 1 PR. Pas de PR multi-stories, pas de story sans PR.

Modifier une PR en cours¶

Tant que la PR n'a pas ete review, si le developpeur modifie l'issue (ajout de details, correction de specs, etc.), il relance mem pr pour mettre a jour la PR.

Le body de la PR est ecrase

mem pr ecrase la description de la PR avec les informations de l'issue. Ne jamais ecrire d'informations directement dans la description de la PR — elles seront perdues au prochain mem pr. Toujours modifier l'issue source.

Merge¶

Regle	Detail
Strategie	Squash merge (chaque PR = 1 commit sur la branche cible)
Approbations	2 requises avant merge
Qui merge	Tout membre de l'equipe une fois les 2 approbations obtenues
Post-merge	La branche est supprimee automatiquement
Cible story	Branche Epic parente si elle existe, sinon `dev`
Cible Epic	`dev` une fois toutes les stories mergees
Interdit	Jamais `main` directement

6. Collaboration cross-repo¶

Avant le developpement : validation par le proprietaire¶

Si on veut developper sur le repo de quelqu'un d'autre :

Discuter d'abord par Discord si necessaire pour aligner sur le besoin.
Creer l'issue complete avec le template rempli (architecture, choix techniques, fichiers concernes, criteres d'acceptance).
Laisser l'issue en Ready — ne pas commencer le developpement.
Ping le proprietaire du repo pour lui signaler que l'issue est prete et qu'on attend sa validation.
Le proprietaire du repo valide, demande des modifications, ou refuse la proposition.
Si des modifications sont demandees, le developpeur corrige l'issue, puis re-ping le proprietaire.
Le developpement ne commence qu'apres validation.

L'objectif : l'issue contient toutes les informations sur l'architecture et les choix techniques. Le proprietaire du repo peut juger si la proposition est alignee avec ses attentes avant que du code soit ecrit. Cela evite le travail perdu.

Choix des reviewers¶

Situation	Reviewers
Code sur le repo de quelqu'un d'autre	Le proprietaire du repo (obligatoire) + une autre personne si pertinent
Code sur son propre repo	Obligatoirement une autre personne, la plus pertinente possible

L'objectif : toujours un regard exterieur sur le code, garantir la qualite, et favoriser la collaboration.

7. Processus de code review¶

Ou et comment faire les retours¶

Les retours de review se font exclusivement via l'interface GitHub, en commentant directement sur les lignes ou blocs de code concernes. Pas de retours par Discord.

Avantages :

Les retours sont visibles dans le contexte du code.
La discussion est tracee et liee a la PR.
L'historique des echanges est conserve.

Qualite des commentaires¶

Un commentaire de review doit etre precis :

Expliquer clairement le probleme ou l'amelioration proposee.
Si possible, suggerer une solution ou une alternative.
Ce n'est toutefois pas au reviewer de faire le travail de developpement a la place du developpeur. Si suggerer une solution demande trop de travail, le reviewer peut se contenter d'expliquer le probleme et laisser au developpeur le soin de trouver la solution.

Apres la review : commentaire recapitulatif¶

Une fois que le reviewer a termine sa review, il poste un commentaire sur la PR pour le signaler. Le developpeur et le reviewer discutent des retours. Une fois d'accord, le developpeur poste un commentaire recapitulatif global sur la PR avec 3 sections :

## Review Summary

### A. Retours qui seront traites
- [ ] Retour 1 (commentaire #link)
- [ ] Retour 2 (commentaire #link)

### B. Retours acceptes en l'etat
- Retour 3 — **Raison** : [pourquoi ce retour ne sera pas traite,
  et pourquoi c'est acceptable]

### C. Retours reportes a une nouvelle issue
- Retour 4 — **Issue** : #NNN — **Raison** : [pourquoi on ne traite
  pas tout de suite, par exemple scope trop large, hors perimetre de
  la story, necessite une refonte plus large, etc.]

Les retours de la section A sont coches au fur et a mesure de leur traitement. Une fois tout traite, le reviewer re-review et approuve.

Si les modifications invalident l'issue¶

Si les retours de review entrainent des changements qui invalident certaines informations de l'issue (changement d'architecture, de fichiers concernes, etc.), ajouter un commentaire sur l'issue indiquant d'aller voir dans la PR les modifications apportees. L'issue reste la source de verite pour la spec initiale, et la PR documente les ajustements faits pendant le developpement.

8. Resume du workflow complet¶

1. EPIC
   → Creation de l'Epic (No Status) avec template complet
   → Decoupage en stories (sub-issues GitHub)

2. STORY — Creation
   → Issue creee en Backlog avec template (meme partiel)
   → Labels : type + domaine + enabler (si applicable)

3. STORY — Refinement
   → Template complete (description, tasks, fichiers, criteres)
   → Si cross-repo : ping du proprietaire pour validation
   → Estimation en story points
   → Enablers verifies → passage en Ready

4. STORY — Developpement
   → Le dev s'assigne → In Progress
   → Cree sa branche : feat/<issue>-description
   → Code, commite au format <Type>(<Context>): <ShortMessage>
   → Coche les checkboxes ## Tasks et ## Acceptance Criteria

5. STORY — Pull Request
   → `mem pr` cree la PR liee automatiquement → In Review
   → Modifications ? → modifier l'issue, relancer `mem pr`

6. STORY — Review
   → 2 reviewers (dont le proprietaire du repo si cross-repo)
   → Retours via commentaires GitHub sur le code
   → Commentaire recapitulatif global (sections A/B/C)
   → Traitement des retours, re-review, approbation

7. STORY — Merge
   → Squash merge, branche supprimee, issue fermee → Done
   → Si enabler : debloquer les issues dependantes

8. EPIC — Fin
   → Toutes les stories Done + Completion Criteria coches → Finish

Workflow de collaboration¶

1. Vue d'ensemble¶

Statuts des stories¶

Statuts des Epics¶

2. Epics¶

Role¶

Template¶

Exemple : Epic #184 — Feat(MemTideCore): Daemon foundations¶

Cycle de vie¶

3. Stories¶

Role¶

Template¶

Exemple : Story #203 — Feat(MemTideCore): Add core architecture foundations with error types and IModule interface¶

L'issue est un document vivant¶

Cycle de vie d'une Story¶

4. Labels¶

Type (bleu — 1 obligatoire)¶

Domaine (vert — 1+ obligatoire)¶

Labels speciaux¶

5. Branches et Pull Requests¶

Nommage des branches¶

mem pr — creer et mettre a jour une PR¶

Regle cle : 1 story = 1 PR¶

Modifier une PR en cours¶

Merge¶

6. Collaboration cross-repo¶

Avant le developpement : validation par le proprietaire¶

Choix des reviewers¶

7. Processus de code review¶

Ou et comment faire les retours¶

Qualite des commentaires¶

Apres la review : commentaire recapitulatif¶

Si les modifications invalident l'issue¶

8. Resume du workflow complet¶

Exemple : Epic #184 — `Feat(MemTideCore): Daemon foundations`¶

Exemple : Story #203 — `Feat(MemTideCore): Add core architecture foundations with error types and IModule interface`¶

`mem pr` — creer et mettre a jour une PR¶