edu-kit – Workflow Git & Règles d’équipe (v1.0.0)

Ce guide présente notre workflow Git et nos règles de collaboration d’équipe, conçus pour garantir des livraisons fiables, des itérations efficaces, et un historique propre et maintenable. En suivant ces directives, nous visons à fluidifier le développement, améliorer la qualité du code et favoriser un environnement d’équipe productif.

1) Discipline des commits — Conventional Commits

Nous suivons la spécification Conventional Commits pour garantir clarté et cohérence.

1.1 Format 

<type>([optional scope]): <description>

[optional body]

[optional footer(s)]

1.2 Types

  • feat : Nouvelle fonctionnalité (MINOR en SemVer)
  • fix : Correctif de bug (PATCH en SemVer)
  • BREAKING CHANGE : Changement majeur (MAJOR en SemVer)
  • Autres : build, chore, ci, docs, style, refactor, perf, test, revert

1.3 Règles

  • Le type est obligatoire, en minuscules.
  • Le scope est optionnel, il donne du contexte.
  • La description ≤ 72 caractères.
  • Le body explique la motivation/l’impact.
  • Le footer sert aux métadonnées ou à BREAKING CHANGE.

1.4 Exemples

  • feat: allow config object to extend other configs
  • feat(lang): add German language
  • docs: correct spelling of CHANGELOG

2) Stratégie de branches

Nous utilisons un modèle de branches structuré avec des conventions de nommage claires.

2.1 Convention de nommage

Modèle : <kind>/<concise-kebab-summary>

  • kind ∈ {feature, bugfix, chore, refactor, docs, ci, perf, style, hotfix}

  • Exemples :

    • feature/loadout-ui
    • bugfix/combat-null-on-death
    • hotfix/critical-fix

2.2 Types de branches

  • Branches principales :
    • main : Toujours publiable, état de production.
    • dev : Branche d’intégration pour le développement en cours.

  • Branches de travail (créées depuis dev) :

    • feature/*, bugfix/*, chore/*, refactor/*, docs/*, perf/*, test/*

  • Branches de hotfix (créées depuis main) :

    • hotfix/*

2.3 Workflow

  1. Créer une branche depuis dev (ou main pour les hotfixes).
  2. Utiliser un nom concis en kebab-case.
  3. Ouvrir une Draft PR tôt.
  4. Pousser de petits commits faciles à relire.
  5. Fusionner après relecture.

3) Stratégie de Pull Request

Les pull requests (PR) sont le mécanisme principal de collaboration, de revue de code et d’intégration. Elles garantissent que les changements sont relus, testés et documentés avant fusion. Une PR doit être claire, concise et cohérente pour aider les reviewers à comprendre rapidement la portée et l’objectif du changement. Chaque PR doit être liée aux work items ou tâches concernés pour fournir du contexte et de la traçabilité.

3.1 Titre de PR

Le titre de la PR sert de nom au changement, de manière similaire à un message de commit, et doit suivre des règles strictes :

Format :

<type>([optional scope]): <short-description>

Règles :

  • Le garder court (≤ 72 caractères).

  • Le type doit correspondre aux types de commit (feat, fix, docs, etc.).

  • Le scope est optionnel mais recommandé pour plus de clarté.

Exemples :

  • feat(ui): implement loadout screen

  • fix(combat): handle null pointer on death

  • docs(readme): update setup instructions

3.2 Description de PR

La description fournit le contexte et la justification du changement. Elle doit répondre à quoi, pourquoi et comment. Référencer systématiquement les work items ou tâches liés dans la description.

Structure

  1. Summary — Vue d’ensemble du changement.

  2. Motivation — Pourquoi ce changement est nécessaire.

  3. Implementation Details — Notes techniques clés ou décisions.

  4. Testing Notes — Comment les reviewers peuvent vérifier le changement.

Modèle

## Summary
Décrivez brièvement ce que fait cette PR.

## Motivation
Pourquoi ce changement est-il nécessaire ? Quel problème résout-il ?

## Implementation Details
Expliquez comment la solution a été implémentée. Mettez en avant les choix de conception.

## Testing Notes
Étapes ou commandes pour tester cette PR. Mentionnez la couverture ou les cas de test manuels.

3.3 Workflow PR

  1. Ouvrir une Draft PR tôt pour partager l’avancement.

  2. Commiter par petits lots pour garder un historique propre.

  3. Demander une review quand c’est stable.

  4. Les checks automatisés doivent passer (CI, linting, tests, SonarQube).

  5. Processus de review :

* Les reviewers donnent des retours constructifs.

* Les conversations doivent être résolues avant approbation.
  1. Exigences d’approbation :
* main/dev → au moins 1 reviewer.
  1. Stratégie :
* Préférer squash pour un historique propre.

* Les hotfixes urgents peuvent contourner le flux normal (avec approbation explicite).

4) Versioning avec des tags

Nous utilisons le Semantic Versioning et des tags Git pour les releases.

4.1 Modèle

v<major>.<minor>.<patch>

4.2 Workflow 

git tag -a v<major>.<minor>.<patch> -m "Release version <major>.<minor>.<patch>"
git push origin v<major>.<minor>.<patch>

4.3 Exemples

  • v1.0.0 Release initiale
  • v1.1.0 Nouvelles fonctionnalités
  • v1.1.1 Correctifs de bugs
  • v2.0.0 Mise à jour majeure

5) Quality Gates

Pour maintenir une qualité de code élevée, nous devons utiliser à la fois des hooks locaux et des pipelines CI.

5.1 Hooks locaux

  • Prettier + ESLint pour le formatage et le linting.

5.2 Pipeline CI

  • Analyse statique (linting, formatage, validation des commits).
  • Tests (≥ 60 % de couverture, SonarQubeCloud Quality Gate A).
  • Vérification de build (build réussi, artefacts de prévisualisation).
  • Contrôles de sécurité (audit des dépendances, scan de secrets).

6) Protection des branches & Gouvernance

6.1 Branches protégées

  • main/dev:
    • Push directs et force push bloqués.
    • PR requise, 1 reviewers, tous les checks validés.

6.2 Politiques de gouvernance

  • Pull Requests obligatoires pour main et dev.
  • Affectation des reviewers selon les zones de code.
  • Validation du build obligatoire avant merge.

Références

Edu-Kit · Documentation interne

Plateforme de virtualisation pédagogique