Contribution conventions
Conventions to respect so a PR is accepted.
Complementary document to the root CONTRIBUTING.md.
Commits
Section titled “Commits”Format
Section titled “Format”Conventional commits with arka-deck scope:
<type>(arka-deck): <short imperative lowercase description>
<optional body — focus on WHY, short paragraphs>
Signed-off-by: <First Last> <email>Co-Authored-By: <co-author if applicable>| Type | Usage |
|---|---|
feat | New feature |
fix | Bug fix |
docs | Documentation only |
refactor | Reorganization with no behavior change |
test | Test addition or fix |
ci | CI/CD, gates, workflows |
style | Format, prettier, lint |
chore | Maintenance, release, deps |
perf | Perf optimization |
Description
Section titled “Description”- Imperative verb, lowercase:
add,fix,remove,update… - Focus on WHY, not just WHAT.
- ≤ 70 chars for the title line.
- Optional body for details, in short paragraphs.
DCO sign-off
Section titled “DCO sign-off”Required on each commit (git commit -s). Without sign-off, the CI blocks the PR.
Signed-off-by: First Last <email@example.com>If forgotten on the last commit: git commit --amend -s.
If forgotten on multiple: git rebase -i HEAD~N --signoff.
Branches
Section titled “Branches”Naming
Section titled “Naming”| Prefix | Usage |
|---|---|
feat/<short-name> | New feature |
fix/<short-name> | Bug fix |
docs/<short-name> | Documentation |
refactor/<short-name> | Refactor |
chore/<short-name> | Maintenance |
hotfix/<X.Y.Z+1> | Urgent hotfix (from a tag) |
Examples: feat/mission-guardian-evidence, fix/cortex-actions-favorites-leak, docs/refonte-bilingue.
Workflow
Section titled “Workflow”- Branch from up-to-date
main. - Work locally, small signed commits.
- Push to your fork.
- PR to
mainof the arka-squad/arka-deck repository. - CI must be green before review.
Pull Requests
Section titled “Pull Requests”Same format as commits: <type>(arka-deck): <description>.
Description
Section titled “Description”## Summary- 1-3 bullets of what changes.
## Test plan- [ ] How to verify it works.- [ ] Edge cases to cover.- [ ] Anti-regressions.
## Links- Issue: #N- ADR: ../../adr/000X-...Prefer one PR per intent. If it exceeds ~500 lines of “interesting” diff (excluding generated), consider splitting.
TypeScript
Section titled “TypeScript”- Strict:
tsc --noEmitmust pass (npm run typecheck). - No
anyunless explicitly justified (comment). - Interfaces > types for outbound ports.
- Relative imports with
.jsextension (ESM TypeScript).
eslint --max-warnings=0 → no warning tolerated. No eslint-disable directives without commented justification.
Format
Section titled “Format”prettier --write (configured). Run npm run format before commit if needed.
For any code change:
- Add or update adjacent tests.
npm testmust pass.- For HTTP routes: server test under
adapters/inbound/web/server/src/__tests__/. - For security (URL, secrets): direct unit test on the policy.
Documentation
Section titled “Documentation”Adding a feature
Section titled “Adding a feature”Update:
- The corresponding addon-firstparty sheet (if addon).
- The provider sheet (if provider).
- The
docs/dev/README.mdindex if new subfolder. CHANGELOG.md([Unreleased]section).
Markdown convention
Section titled “Markdown convention”- Minimal frontmatter (bilingual header with EN/FR link + back-to-index).
## Contentsif > 4 sections.- Fenced code with language (
```ts,```bash). - Tables for structured lists.
Bilingual
Section titled “Bilingual”Active guides have a FR version (*.md) and EN (*.en.md). Any modification touches both. No divergence.
Security
Section titled “Security”- No API key in commits (gitleaks blocks).
- No secret in logs.
- No modification of
.claude/settings.json(user settings). - No reference to
.input/(internal, gitignored). - No SSRF override by default (
ARKA_DECK_CORTEX_ALLOW_UNSAFE_URLreserved for dev).
Report a vulnerability via the SECURITY.md procedure.
See also
Section titled “See also”- Root CONTRIBUTING.md: ../../../CONTRIBUTING.md
- Code of Conduct: ../../../CODE_OF_CONDUCT.md
- AI agent guide: ./working-rules