Conventions de contribution

Conventions à respecter pour qu’une PR soit acceptée.

Document complémentaire à CONTRIBUTING.md racine.

Commits

Format

Conventional commits avec scope arka-deck :

<type>(arka-deck): <description courte impérative en minuscules>

<corps optionnel — focus sur le WHY, paragraphes courts>

Signed-off-by: <Prénom Nom> <email>
Co-Authored-By: <co-auteur si applicable>

Types

Type	Usage
`feat`	Nouvelle fonctionnalité
`fix`	Correction de bug
`docs`	Documentation seulement
`refactor`	Réorganisation sans changement de comportement
`test`	Ajout ou correction de tests
`ci`	CI/CD, gates, workflows
`style`	Format, prettier, lint
`chore`	Maintenance, release, deps
`perf`	Optimisation perf

Description

Verbe impératif, minuscules : add, fix, remove, update…
Focus sur le WHY, pas seulement le WHAT.
≤ 70 caractères pour la ligne titre.
Corps optionnel pour le détail, en paragraphes courts.

DCO sign-off

Obligatoire sur chaque commit (git commit -s). Sans sign-off, la CI bloque la PR.

Signed-off-by: Prénom Nom <email@example.com>

Si oublié sur le dernier commit : git commit --amend -s.

Si oublié sur plusieurs : git rebase -i HEAD~N --signoff.

Branches

Naming

Préfixe	Usage
`feat/<nom-court>`	Nouvelle fonctionnalité
`fix/<nom-court>`	Correction de bug
`docs/<nom-court>`	Documentation
`refactor/<nom-court>`	Refactor
`chore/<nom-court>`	Maintenance
`hotfix/<X.Y.Z+1>`	Hotfix urgent (depuis un tag)

Exemples : feat/mission-guardian-evidence, fix/cortex-actions-favorites-leak, docs/refonte-bilingue.

Workflow

Brancher depuis main à jour.
Travailler localement, commits petits et signés.
Push vers votre fork.
PR vers main du dépôt arka-squad/arka-deck.
CI doit être verte avant review.

Pull Requests

Titre

Même format que les commits : <type>(arka-deck): <description>.

Description

## Résumé
- 1-3 puces de ce qui change.

## Test plan
- [ ] Comment vérifier que ça marche.
- [ ] Cas limites à couvrir.
- [ ] Anti-régressions.

## Liens
- Issue : #N
- ADR : ../../adr/000X-...

Taille

Préférer une PR par intention. Si elle dépasse ~500 lignes de diff “intéressantes” (hors générées), envisager de découper.

Code

TypeScript

Strict : tsc --noEmit doit passer (npm run typecheck).
Pas de any sauf justification explicite (commentaire).
Interfaces > types pour les ports outbound.
Imports relatifs avec extension .js (ESM TypeScript).

Lint

eslint --max-warnings=0 → aucun warning toléré. Pas de directives eslint-disable sans justification commentée.

Format

prettier --write (configuré). Lancer npm run format avant commit si besoin.

Tests

Pour toute modification de code :

Ajouter ou mettre à jour les tests adjacents.
npm test doit passer.
Pour les routes HTTP : test serveur sous adapters/inbound/web/server/src/__tests__/.
Pour la sécurité (URL, secrets) : test unitaire direct sur la politique.

Documentation

Ajouter une fonctionnalité

Mettre à jour :

La fiche addon-firstparty correspondante (si addon).
La fiche provider (si provider).
L’index docs/dev/README.md si nouveau sous-dossier.
Le CHANGELOG.md (section [Unreleased]).

Convention markdown

Frontmatter minimal (header bilingue avec lien EN/FR + retour index).
## Sommaire si > 4 sections.
Code-fence avec langage ( ```ts, ```bash).
Tableaux pour les listes structurées.

Bilingue

Les guides actifs ont une version FR (*.md) et EN (*.en.md). Toute modification touche les deux. Pas de divergence.

Sécurité

Pas de clé API dans les commits (gitleaks bloque).
Pas de secret dans les logs.
Pas de modification de .claude/settings.json (settings utilisateur).
Pas de référence à .input/ (interne, gitignored).
Pas d’override SSRF par défaut (ARKA_DECK_CORTEX_ALLOW_UNSAFE_URL réservé au dev).

Signaler une vulnérabilité via la procédure SECURITY.md.

Voir aussi

CONTRIBUTING/ racine : ../../../CONTRIBUTING.md
Code of Conduct : ../../../CODE_OF_CONDUCT.md
Guide agent IA : ./working-rules