Contribuer via le workflow Git et pull request

Ce guide décrit le workflow Git utilisé par le projet gitrust pour toute contribution : nouvelle fonctionnalité, correctif, ou documentation.

Pré-requis

Accès en lecture/écriture au dépôt (ou à votre fork).
Environnement de développement opérationnel (voir tutorials/01-getting-started.md).

Créer une branche depuis main

Toujours partir d'un main à jour :

git switch main
git pull --rebase origin main
git switch -c <type>/<numéro>-<description-courte>

Convention de nommage des branches :

Préfixe	Usage
`feat/`	Nouvelle fonctionnalité
`fix/`	Correctif de bug
`refactor/`	Refactorisation sans changement de comportement
`docs/`	Documentation uniquement
`test/`	Tests uniquement

Exemples : feat/42-webhook-dispatch, fix/88-slug-leading-dash, docs/15-api-rest.

Conventions de commit

Gitrust suit les Conventional Commits. Le format est :

<type>(<scope optionnel>): <description en impératif>

[corps optionnel]

[footer : Closes #N, BREAKING CHANGE, etc.]

Types acceptés : feat, fix, refactor, test, docs, chore, perf.

Exemples valides :

feat(webhooks): ajouter la signature HMAC-SHA256 sur les livraisons
fix(slug): rejeter les slugs commençant par un tiret (Closes #42)
test(import): ajouter test hermétique pour le timeout worker

Règle des petits commits atomiques : un commit = un changement logique cohérent. Évitez les commits « WIP » ou « fix fix fix » — utilisez git commit --amend ou git rebase -i pour réécrire l'historique avant de pousser.

Rebase avant push

Avant de pousser votre branche, rebasez-la sur main pour obtenir un historique linéaire :

git fetch origin
git rebase origin/main

En cas de conflit, résolvez-les fichier par fichier, puis :

git add <fichier-résolu>
git rebase --continue

Ne fusionnez jamais main dans votre branche de feature (git merge main) — cela crée des commits de merge parasites.

Checklist pre-merge (QA obligatoire)

Avant d'ouvrir la PR, vérifiez chaque point :

cargo fmt --all -- --check — zéro diff de formatage
cargo clippy --workspace -- -D warnings — zéro warning
cargo test --workspace — 100 % de tests passants
npm run test:e2e — tests Playwright passants (si templates ou routes modifiés)
CSS rebuild : npx tailwindcss -i static/css/input.css -o static/css/style.css --minify (si templates modifiés)
Aucun secret, token ou clé en clair dans le code ou les logs
Aucune modification dans crates/rustwarden-core/ (framework read-only)

Voir la checklist complète dans passer-la-qa-avant-merge.md.

Ouvrir la pull request

Poussez votre branche :

git push origin <votre-branche>

Sur la plateforme gitrust, naviguez vers /{owner}/gitrust/pulls/new et remplissez :

Titre : message de commit principal (convention Conventional Commits).
Corps : contexte du problème, solution choisie, alternatives considérées, lien vers l'issue (Closes #N).
Reviewers : assignez au moins un reviewer.
Labels : appliquez les labels de classification appropriés.

Critères d'approbation

Un reviewer approuve quand :

Tous les gates QA passent (CI verte).
La logique métier est correcte et les cas limites sont couverts par des tests.
Aucun .unwrap(), .expect(), ou panic!() non justifié.
Le diff ne contient pas de changements de périmètre non demandés.

Stratégie de merge par défaut

Gitrust utilise le merge commit pour conserver la traçabilité des branches dans l'historique. Le squash est réservé aux PRs de correction mineure (1-2 commits). Le rebase-merge est proscrit car il réécrit les SHA des commits existants.

Après le merge

Supprimez votre branche locale et distante :

git switch main
git pull --rebase origin main
git branch -d <votre-branche>
git push origin --delete <votre-branche>

Vérifiez que l'issue liée est bien fermée automatiquement par le Closes #N dans le message de commit ou le corps de la PR.

Eric / documentation