Standards de code
Les conventions ci-dessous existent pour que les contributeurs n’aient pas à les redéduire à chaque PR, et pour que la base de code reste lisible à mesure qu’elle grandit.
Branches
Section intitulée « Branches »mainne contient que du stable : elle reçoit uniquement des jalons testés et fonctionnels issus dedev. Le force-push surmainest interdit. Pousser directement surmainsans merge relu au préalable depuisdevest interdit.devest la branche d’intégration. Les branches de fonctionnalité fusionnent dansdev;devalimentemainaux jalons de publication.feat/<scope>,fix/<scope>,chore/<scope>pour les branches de travail. Supprimez-les immédiatement après le merge ; seulesdevetmainsont durables.
- Format :
<area>: <imperative summary>. Par exemple :assets: handle 0-byte uploads,web: fix viewer crash on EXR with no exif. - Un changement logique par commit. Si un refactoring et un correctif sont arrivés ensemble, séparez-les.
- Pas de lignes de coauteur Claude / IA. Le changement est celui du contributeur.
- Mentionnez le numéro d’issue/PR dans le corps du message, pas dans le sujet.
- Pour les messages de commit multilignes, utilisez des HEREDOC : le formatage est préservé à travers les shells.
Pull requests
Section intitulée « Pull requests »- Les PR de fonctionnalité et de correctif ciblent
dev. La seule PR versmainest la PR de publicationdev → main, ouverte dans le cadre du processus de release (RELEASING.md). - La description de la PR explique pourquoi, pas quoi. Le diff montre déjà le quoi.
- Référencez l’ADR concerné (
See ADR 0036) et toute issue liée. ./scripts/test.shdoit passer en local avant l’ouverture de la PR. La CI le relance ; une CI rouge est bloquante.- Squash-merge pour les branches de fonctionnalité ; merge commit pour la publication
dev → main.
Style Go
Section intitulée « Style Go »Les règles non évidentes. La CI impose le formatage avec gofmt (le job échoue si gofmt -l liste un fichier sous app/) et n’exécute aucun autre linter Go.
- Les erreurs remontent. Aucune erreur avalée en silence, pas de
_ = err. Si une erreur peut réellement être ignorée sans risque, écrivez un commentaire qui explique pourquoi. - Faites confiance au code interne, validez aux frontières. Ne revalidez pas des entrées que vos propres appelants ont déjà validées. Validez aux points d’entrée HTTP (fonctions handler) et aux points d’entrée des systèmes externes (backends de stockage, connecteurs).
- Pas de vérifications de nil défensives sur des valeurs garanties non nil. Si le système de types ou le framework garantit qu’une valeur n’est pas nil, n’ajoutez pas une vérification qui « ne peut jamais se déclencher » ; elle fait douter le lecteur de la garantie.
- Les commentaires expliquent le pourquoi, pas le quoi. Un code qui se lit comme du code n’a pas besoin d’être narré ; un code qui cache une contrainte, un contournement ou un invariant non évident, si.
- Gardez les commentaires de documentation courts. Une ou deux lignes suffisent en général pour un symbole exporté ; le lecteur de godoc est un ingénieur qui connaît déjà Go. Écrivez davantage quand les appelants en ont besoin : un contrat non évident, une contrainte de sécurité, un comportement de concurrence ou un invariant, comme le comportement du verrou consultatif (advisory lock) documenté sur
db.Migrate. - Organisation par domaine. Chaque domaine possède son répertoire
internal/<domain>/. Les appels entre domaines passent par la couche handler ou par de petites interfaces injectées en dépendance, jamais en saisissant directement le dépôt d’un autre domaine.
sqlc + pgx
Section intitulée « sqlc + pgx »- DOUBLE PRECISION plutôt que NUMERIC pour les flottants. NUMERIC est mappé sur
pgtype.Numericdans pgx, ce qui est pénible à manipuler depuis Go. - Le motif PATCH avec COALESCE pour les mises à jour partielles :
UPDATE foo SET col = COALESCE(sqlc.narg('col'), col), et passeznilpour laisser la colonne intacte. - Régénérez avec
./scripts/generate.shdepuis la racine du dépôt après chaque modification dequeries.sqlou deopenapi.yaml. Les étapes sqlc et oapi-codegen s’exécutent dans des conteneurs ; le script utilise aussi des utilitaires shell de l’hôte pour régénérer le PanicShim partagé. Ne modifiez pas à la mainqueries.sql.goni aucun autre fichier généré. - La CI détecte le code généré obsolète. Le job de dérive du code généré régénère le code Go et échoue si le résultat diffère de ce que vous avez commité. S’il échoue, relancez
./scripts/generate.sh, relisez le diff et commitez-le.
- Les tests d’intégration utilisent un vrai Postgres. Pas de mocks de base de données. La divergence entre mock et production nous a déjà piégés ; le script de test (
./scripts/test.sh) exécute chaque test sur une base jetable dans le Postgres de la stack Docker Compose. - Les tests ne touchent jamais votre base de développement.
./scripts/test.shles exécute sur une base<db>_testséparée, qu’il réinitialise au début de chaque exécution ; votre compte administrateur et vos données ne sont donc pas affectés. - Les shims de test du serveur strict OpenAPI embarquent le
strictservershim.PanicShimpartagé (voir « Ce que nous ne faisons pas » plus bas), si bien qu’une nouvelle opération n’a pas besoin de stub propre à son package. - Pas de mocks pour des assertions du type « est-ce que ceci est appelé ». Si vous voulez vérifier qu’une fonction a été appelée, refactorisez pour que l’effet de bord soit observable (une ligne dans une table, une tâche dans une file), puis testez cet effet de bord.
Style frontend (Svelte 5)
Section intitulée « Style frontend (Svelte 5) »- Les runes hors composants vont dans des modules
.svelte.ts. Svelte 5 compile les runes ($state,$derived,$effect) dans les composants.svelteet dans les modules.svelte.jsou.svelte.ts; dans un simple fichier.tsou.js, elles ne sont pas compilées et le code ne se comportera pas comme prévu. Svelte accepte l’une ou l’autre extension de module ;.svelte.tsest la convention de ce projet, en cohérence avec sa base de code TypeScript. web/src/lib/components/est le réservoir de composants partagés. Les composants propres à une route vivent à côté de la route à laquelle ils appartiennent.- Vérifiez les types avant de pousser. Avec la stack Compose en cours d’exécution, le conteneur
weba les dépendances installées et monte votre répertoireweb/sur/app:docker compose exec -T web sh -c 'cd /app && npm run check'. Pour l’exécuter sur l’hôte à la place, installez les dépendances verrouillées avecnpm cidansweb/et lancez-ynpm run check. - Régénérez le schéma d’API après toute modification de
openapi.yaml:npm run generate:apidepuisweb/. Le schéma est ignoré par git (gitignored), donc une copie obsolète n’affecte que vos vérifications locales : la CI le génère à neuf à partir deopenapi.yaml, puis exécute svelte-check, vitest et un build vite. Le côté Go de l’API est généré séparément, par./scripts/generate.sh. - Les chaînes i18n vivent dans
web/src/lib/i18n/<locale>.json. Les nouvelles surfaces ajoutent la clé anglaise ; les ébauches des autres langues suivent../scripts/generate.shcopieen.jsondans l’arborescence Go, donc relancez-le après avoir modifié les chaînes anglaises, sinon la vérification de dérive de la CI échoue. - Pas de
console.logdans le code commité. Les instructions console ne sont que du bruit de débogage.
Commentaires
Section intitulée « Commentaires »Par défaut, pas de commentaire. N’en ajoutez un que lorsque le POURQUOI n’est pas évident : une contrainte cachée, un invariant subtil, un contournement pour un bug précis, un comportement qui surprendrait un lecteur.
Ce qu’il ne faut pas écrire :
- Ce que fait le code : des identifiants bien nommés le disent déjà.
- Des références à la tâche / au correctif / aux appelants du moment (« utilisé par X », « ajouté pour le flux Y », « gère le cas de l’issue #123 ») : cela relève de la description de la PR et pourrit dans la base de code.
- Des commentaires de plusieurs paragraphes : si une chose demande trois paragraphes d’explication, elle demande probablement un ADR.
Tester en local avant de pousser
Section intitulée « Tester en local avant de pousser »Exécutez ./scripts/test.sh depuis la racine du dépôt et assurez-vous qu’il passe avant tout push. Le script :
- A besoin du
.envcréé par./scripts/bootstrap.shet de la stack Docker Compose déjà démarrée (docker compose up -d). - Exécute les tests Go sur une base
<db>_testséparée dans le Postgres de cette stack, réinitialisée au début de chaque exécution. Dans ungit worktreelié, le nom de la base reçoit un court hachage du chemin du checkout, et cette base est supprimée à la fin de l’exécution (AA_TEST_KEEP_DB=1la conserve). - Laisse votre base de développement intacte.
- Ne couvre que la suite Go.
--with-s3démarre aussi MinIO et exécute les tests du stockage S3.
Les vérifications du frontend sont distinctes : npm run check, npm test (vitest) et npm run build, à lancer depuis web/ ou dans le conteneur web.
La CI couvre davantage que le script local. Le job d’intégration exécute ./scripts/test.sh sur une stack fraîchement construite ; d’autres jobs vérifient gofmt, régénèrent le code et échouent en cas de dérive, et exécutent la vérification de types, les tests unitaires et le build du frontend. Les pull requests qui ne modifient que la documentation sautent ces jobs. Lancer d’abord les étapes équivalentes en local évite généralement un aller-retour.
Migrations de base de données
Section intitulée « Migrations de base de données »Les migrations se trouvent dans app/internal/db/migrations/, sous forme de fichiers NNNNN_*.sql gérés par goose. app/schema.sql est un dump du schéma seul d’une base construite en exécutant les migrations ; sqlc lit ce fichier, et non les migrations, pour générer le code.
- Pendant la bêta (avant la v1.0.0) : les nouvelles migrations sont ajoutées comme de simples fichiers
NNNNN_*.sqlau-dessus de la base de référence v0.1.0, conformément à l’ADR 0046. Elles seront à nouveau fusionnées dans une nouvelle base de référence au tag v1.0.0. Les installations existantes se mettent à jour en exécutant les migrations ajoutées, ce qui se fait automatiquement au démarrage. - Après la v1.0 : uniquement vers l’avant, pour toujours. Plus de squash. Des opérateurs réels avec des données réelles dépendent du bon fonctionnement de
goose updepuis n’importe quelle version précédemment livrée. - Les contraintes CHECK reflètent des constantes Go typées, conformément à l’ADR 0042. Quand la migration impose un ensemble fermé au niveau de la base, le même ensemble existe sous forme de constantes typées dans le package propriétaire ; les deux moitiés arrivent dans la même PR.
- Régénérez
app/schema.sqldans le même commit que celui qui ajoute une migration (l’en-tête du fichier donne les étapes) ; ne le modifiez pas à la main. La CI ne le compare pas aux migrations, donc les relecteurs vérifient que les deux concordent.
Pas de comparaisons de produits dans le code source
Section intitulée « Pas de comparaisons de produits dans le code source »Le code source (Go, Svelte, commentaires SQL, OpenAPI) ne doit pas s’appuyer sur des comparaisons nommées avec des produits concurrents ou d’inspiration. Les comparaisons nommées vieillissent mal quand le produit change et déroutent les lecteurs qui ne savent pas ce que signifie « AFFiNE-shaped ».
Concrètement :
- Ne pas écrire « Mastodon-shaped activity dispatch » → écrire « ArchivePub activity dispatch ».
- Ne pas écrire « the prior generation’s
resource_nodetable » → énoncer la conception pour elle-même. - Ne pas écrire « AFFiNE’s element-typed model » → écrire « an element-typed model ».
- Ne pas écrire « Frame.io-style timestamped comments » → écrire « asset-anchored timestamped comments ».
- Ne pas écrire « PeerTube has to move every byte » → supprimer la comparaison ; décrire simplement ce que nous faisons.
- Ne pas conserver les noms de colonnes
rs_user_id/rs_resource_id; les renommer enexternal_user_id, neutre, ou les supprimer si la colonne n’est plus utilisée.
Exemptions. Deux endroits conservent volontairement des références nommées à des produits amont / concurrents :
- Les ADR et
docs/research/: documents de décision et archives historiques. - Les surfaces d’attribution de licence : avis sur les dépendances tierces exigés par leurs licences (reconnaître une source n’est pas comparer). L’ancienne attribution de la base de fork ResourceSpace a été retirée une fois le code dérivé de RS supprimé et le projet relicencié sous AGPL-3.0 (ADR 0001 → remplacé par l’ADR 0040).
Tout le reste du code source reste neutre.
Ce que nous ne faisons pas
Section intitulée « Ce que nous ne faisons pas »- Des shims de rétrocompatibilité pour du code dont aucun appelant réel ne dépend. Si vous renommez une fonction et que rien de réel n’utilisait l’ancien nom, supprimez l’ancien nom. Ne gardez pas de zombies « pour la compatibilité ».
- Des chemins de repli hérités dans les handlers déjà câblés. Selon l’ADR 0044, tout handler qui émet des activités de fédération utilise
WithEmission/WithEmissionFncomme unique chemin de code. Le motif « si le writer d’activités n’est pas câblé, se rabattre sur l’écriture du domaine » est interdit : en production il ne se déclenche jamais ; dans les tests il masque l’invariant de justesse de la livraison fédérée. Les tests câblent le writer d’activités dans leur setup ; il n’y a pas de second chemin. - Des stubs de test qui prolifèrent par package. Les tests du serveur strict OpenAPI utilisent le
internal/openapi/strictservershim.PanicShimpartagé. Embarquez-le ; ne surchargez que les méthodes que le test exerce réellement. Ne créez pas un nouveau fichier de shim propre au package avec N méthodes qui paniquent à chaque nouvelle opération OpenAPI. - Des abstractions spéculatives. Trois lignes similaires valent mieux qu’une abstraction prématurée pour deux. Le troisième appelant justifie l’utilitaire ; le deuxième, non.
--no-verifysur les commits. Le dépôt ne fournit aucun hook Git, mais si vous exécutez les vôtres, ne les contournez pas : si un hook échoue, corrigez le problème sous-jacent.- Des contournements par
--force-recreatepour des conteneurs obsolètes dans les chemins de production. C’est acceptable en développement local quand les changements du binaire Go ne sont pas pris en compte ; la production obéit à d’autres règles de cycle de vie.
En cas de doute
Section intitulée « En cas de doute »Lisez les PR récemment fusionnées pour voir comment la base actuelle de contributeurs écrit son code. Référez-vous à l’ADR des conventions (0035) pour les usages en matière de documentation. Si la réponse reste floue, posez la question dans la PR ou dans une issue ; le responsable du projet préfère répondre une fois plutôt que démêler dix pratiques divergentes plus tard.