From 303dbedcdda5043e5fe4171bd89e8dcbec595f5b Mon Sep 17 00:00:00 2001 From: Dan Allaire Date: Sun, 26 Oct 2025 10:56:03 -0400 Subject: [PATCH] docs(collab): conventions git, PR template, issue templates, CODEOWNERS --- .forgejo.labels.json | 42 +++++++++++++ .gitea/ISSUE_TEMPLATE/bug_report.md | 21 ++++--- .gitea/ISSUE_TEMPLATE/feature_request.md | 21 +++++-- .gitea/PULL_REQUEST_TEMPLATE.md | 17 +++++ CODEOWNERS | 6 ++ CONTRIBUTING.md | 80 ++++++++++++++++++++++-- README-COLLAB.md | 25 ++++++++ docs/engineering/git-conventions.md | 29 +++++++++ scripts/check_branch.sh | 13 ++++ templates/.gitmessage.txt | 7 +++ 10 files changed, 241 insertions(+), 20 deletions(-) create mode 100644 .forgejo.labels.json create mode 100644 .gitea/PULL_REQUEST_TEMPLATE.md create mode 100644 CODEOWNERS create mode 100644 README-COLLAB.md create mode 100644 docs/engineering/git-conventions.md create mode 100755 scripts/check_branch.sh create mode 100644 templates/.gitmessage.txt diff --git a/.forgejo.labels.json b/.forgejo.labels.json new file mode 100644 index 0000000..12842b3 --- /dev/null +++ b/.forgejo.labels.json @@ -0,0 +1,42 @@ +[ + { + "name": "bug", + "color": "#d73a4a", + "description": "Quelque chose ne fonctionne pas" + }, + { + "name": "feature", + "color": "#a2eeef", + "description": "Demande de fonctionnalité" + }, + { + "name": "docs", + "color": "#0075ca", + "description": "Documentation" + }, + { + "name": "security", + "color": "#8a2be2", + "description": "Sécurité / durcissement" + }, + { + "name": "infra", + "color": "#e99695", + "description": "Infra / CI / pipelines" + }, + { + "name": "help wanted", + "color": "#008672", + "description": "Contributions bienvenues" + }, + { + "name": "good first issue", + "color": "#7057ff", + "description": "Idéal pour débuter" + }, + { + "name": "blocked", + "color": "#b60205", + "description": "Bloqué / dépendance" + } +] diff --git a/.gitea/ISSUE_TEMPLATE/bug_report.md b/.gitea/ISSUE_TEMPLATE/bug_report.md index db72cd5..0912068 100644 --- a/.gitea/ISSUE_TEMPLATE/bug_report.md +++ b/.gitea/ISSUE_TEMPLATE/bug_report.md @@ -1,11 +1,16 @@ ---- name: Bug -about: Rapport de bogue +about: Signaler un problème +title: "[bug] " +labels: ["bug"] --- -**Comportement attendu** -**Comportement observé** +**Description** +Comportement observé vs attendu + **Reproduire** -1. -2. -3. -**Contexte** (OS, version, logs) +Étapes / commandes + +**Preuves** +Logs / captures (masquez toute donnée sensible) + +**Contexte** +Version, env, tenant, C5/gateway si concerné diff --git a/.gitea/ISSUE_TEMPLATE/feature_request.md b/.gitea/ISSUE_TEMPLATE/feature_request.md index c9661d7..9f31b43 100644 --- a/.gitea/ISSUE_TEMPLATE/feature_request.md +++ b/.gitea/ISSUE_TEMPLATE/feature_request.md @@ -1,7 +1,16 @@ +name: Feature +about: Nouvelle fonctionnalité / amélioration +title: "[feat] " +labels: ["feature"] --- -name: Demande de fonctionnalité -about: Proposition d'amélioration ---- -**Problème à résoudre** -**Solution proposée** -**Impacts (doc, SSOT, CI)** +**Problème à résoudre / valeur** +Contexte / objectif + +**Approche proposée** +Idées techniques, impact C5/CI/docs + +**Preuves attendues** +SBOM/signature, tests, docs + +**Dépendances** +Issues/PRs liées diff --git a/.gitea/PULL_REQUEST_TEMPLATE.md b/.gitea/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..4fe9bf1 --- /dev/null +++ b/.gitea/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,17 @@ +## Objet de la PR + + +## Checklist +- [ ] CI verte (scan secrets, build, SBOM, signature, lint preuves) +- [ ] Aucune fuite de secret dans le diff +- [ ] `registrar.yaml` mis à jour si nécessaire (et **valide**) +- [ ] Preuves ajoutées/mises à jour (`/evidence/...`) si pertinent +- [ ] C5: mTLS/OPA testés (captures/artefacts joints) si modifié +- [ ] Docs mises à jour (`docs/constitution/03_*` / `03_annexes.md`) +- [ ] 2 reviewers (infra/sécu si applicable) + +### Liens / Issues +Closes # + +### Captures / Preuves + diff --git a/CODEOWNERS b/CODEOWNERS new file mode 100644 index 0000000..0790f98 --- /dev/null +++ b/CODEOWNERS @@ -0,0 +1,6 @@ +# CODEOWNERS — utilisez des équipes/alias Forgejo (ex: @Alliance-Boreale/secops) +/docs/constitution/ @Alliance-Boreale/docs +/.forgejo/workflows/ @Alliance-Boreale/ci +/security/ @Alliance-Boreale/secops +/evidence/ @Alliance-Boreale/secops +/registrar*.yaml @Alliance-Boreale/infra diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index bcb9c6a..b2169fd 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,6 +1,74 @@ -# Contribuer -1. Fork/branche: `feat/...`, `fix/...`, `docs/...`. -2. Respecter la charte DNS/PKI et le plan IP v3. -3. Mettre à jour la doc (`docs/`) si comportement/standard change. -4. Lint YAML: `yamllint` (via CI), SSOT: `node configure/export.mjs`. -5. Tests: `node configure/tests/test.mjs`. +# Contribuer à l'Alliance Boréale + +Bienvenue ! Voici les conventions pour garder un dépôt propre, lisible et sûr. + +## TL;DR (workflow standard) +1. `git switch -c ` selon la convention ci-dessous +2. Commits **Conventional Commits** +3. Ouvre une PR (2 reviewers requis pour dossiers infra/sécu) +4. CI **verte** (scan secrets, SBOM, signature, lint preuves) +5. Mets à jour la doc/annexes si besoin +6. Merge (Squash & Merge recommandé), supprime la branche + +--- + +## Nommage des branches +Format : `{type}/{scope}-{description-courte}` *(kebab-case, pas d’accents)* + +**Types acceptés :** +- `feat` (nouvelle fonctionnalité) +- `fix` (correctif) +- `docs` (documentation) +- `ci` (pipeline / outils CI/CD) +- `refactor` (refacto sans changement fonctionnel) +- `perf` (performance) +- `test` (tests) +- `chore` (entretien, dépendances) +- `security` (politiques, durcissement, corrections sécu) +- `hotfix` (urgence prod) +- `release` (préparation release) + +**Exemples :** +- `feat/lot1-starter-kit` +- `security/opa-policies-c5` +- `docs/03-annexes-label` +- `fix/ci-cosign-verification` + +--- + +## Commits : Conventional Commits +Format de message : `type(scope): description brève` + +**Exemples :** +- `feat(registraire): ajoute schéma security + exemple YAML` +- `ci(signing): active cosign keyless et vérification` +- `docs(03): ajoute Annexe B - catalogue de preuves` +- `security(logs): active object-lock sur le bucket` + +> *Scope* optionnel. Développe dans le **corps** : *motivation, breaking changes, liens vers issues*. + +--- + +## Pull Requests +- **CI verte** : `.forgejo/workflows/security-supplychain.yml` doit réussir +- **Pas de secrets** en clair (scan Gitleaks = 0) +- **SBOM + signatures/attestations** présents pour artefacts buildés +- **Preuves** mises à jour si pertinent (`/evidence/...`) +- **OPA** / **mTLS** testés si changement C5 +- **Docs** mises à jour (ex: `docs/constitution/03_*.md` ou `03_annexes.md`) +- Liaison à une issue : `Closes #` (si applicable) + +**Stratégie de merge** : *Squash & Merge* recommandé pour garder l’historique propre. + +--- + +## Sécurité (rappels) +- MFA résistante au hameçonnage pour comptes à privilèges (FIDO2) +- Secrets **par référence** (Vault) uniquement +- Runners CI **éphémères**, jetons courts, réseau sortant minimal +- Logs immu **90j** (Object-Lock/WORM), alerte test lors de nouvelles règles + +--- + +## Code of Conduct +Restez respectueux et bienveillants; pas de données sensibles dans les issues/PR publiques. diff --git a/README-COLLAB.md b/README-COLLAB.md new file mode 100644 index 0000000..5ab5e02 --- /dev/null +++ b/README-COLLAB.md @@ -0,0 +1,25 @@ +# Pack Conventions Collaboration — Alliance Boréale + +Contient : +- `CONTRIBUTING.md` — règles de contribution (branches, commits, PRs, sécurité) +- `docs/engineering/git-conventions.md` — détails pratiques +- `.gitea/PULL_REQUEST_TEMPLATE.md` — checklist PR +- `.gitea/ISSUE_TEMPLATE/*` — modèles d'issues +- `CODEOWNERS` — propriétaires de chemins (à adapter à vos équipes) +- `scripts/check_branch.sh` — vérification du nom de branche +- `templates/.gitmessage.txt` — modèle de message de commit +- `.forgejo.labels.json` — labels à importer dans la Forge + +## Installation rapide +Déposez tout à la racine du dépôt, puis : +```bash +# modèle de commit pour ce repo +git config commit.template templates/.gitmessage.txt + +# hook local pour valider le nom de branche avant push +echo './scripts/check_branch.sh' > .git/hooks/pre-push && chmod +x .git/hooks/pre-push + +# importer les labels (via API Forgejo ou à la main) +# API: POST /repos/{owner}/{repo}/labels avec le contenu de .forgejo.labels.json +``` +Pensez à ajuster `CODEOWNERS` avec vos **vrais** groupes/équipes Forgejo (ex: @Alliance-Boreale/secops). diff --git a/docs/engineering/git-conventions.md b/docs/engineering/git-conventions.md new file mode 100644 index 0000000..7a0a529 --- /dev/null +++ b/docs/engineering/git-conventions.md @@ -0,0 +1,29 @@ +# Conventions Git — Alliance Boréale + +## Branches +- `{type}/{scope}-{description}` +- *kebab-case*, ASCII simple, 50–60 caractères max +- Durée de vie courte; suppression après merge +- Pas de commits directement sur `main` (branches protégées) + +## Types (rappel) +feat, fix, docs, ci, refactor, perf, test, chore, security, hotfix, release + +## Commits +- Titre ≤ 72 chars +- Corps : *motivation, contexte, liens, breaking changes* +- `revert:` autorisé (réf. au commit original) + +## Rebase / Merge +- Préférez **Squash & Merge** (historique lisible) +- Rebase interactif autorisé avant PR pour nettoyer + +## Tags / Releases (optionnel) +- SemVer : `vX.Y.Z` +- Changelog généré depuis Conventional Commits (outil libre au choix) + +## Hooks (optionnel) +- `pre-push` : validation nom de branche & scan rapide +- `prepare-commit-msg` : pré-remplir le modèle de commit + +Voir `scripts/check_branch.sh` et `templates/.gitmessage.txt`. diff --git a/scripts/check_branch.sh b/scripts/check_branch.sh new file mode 100755 index 0000000..3ee2bb7 --- /dev/null +++ b/scripts/check_branch.sh @@ -0,0 +1,13 @@ +#!/usr/bin/env bash +# Validate branch name against {type}/{scope}-{desc} +set -euo pipefail +bname="$(git rev-parse --abbrev-ref HEAD)" +re='^(feat|fix|docs|ci|refactor|perf|test|chore|security|hotfix|release)\/[a-z0-9]+(-[a-z0-9]+)*$' +if [[ "$bname" =~ $re ]]; then + echo "Branch name OK: $bname" + exit 0 +else + echo "ERROR: Branch '$bname' ne respecte pas la convention {type}/{scope}-{desc}." + echo "Exemples: feat/lot1-starter-kit, security/opa-policies-c5" + exit 1 +fi diff --git a/templates/.gitmessage.txt b/templates/.gitmessage.txt new file mode 100644 index 0000000..7c920e8 --- /dev/null +++ b/templates/.gitmessage.txt @@ -0,0 +1,7 @@ +# Titre (Conventional Commit): type(scope): description brève (≤72) +# Corps (optionnel): motivation, contexte, liens, breaking changes +# +# Exemples: +# feat(registraire): ajoute schéma security + exemple YAML +# ci(signing): active cosign keyless et vérification +# docs(03): ajoute Annexe B - catalogue de preuves