Aller au contenu

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.

  • main ne contient que du stable : elle reçoit uniquement des jalons testés et fonctionnels issus de dev. Le force-push sur main est interdit. Pousser directement sur main sans merge relu au préalable depuis dev est interdit.
  • dev est la branche d’intégration. Les branches de fonctionnalité fusionnent dans dev ; dev alimente main aux jalons de publication.
  • feat/<scope>, fix/<scope>, chore/<scope> pour les branches de travail. Supprimez-les immédiatement après le merge ; seules dev et main sont 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.
  • Les PR de fonctionnalité et de correctif ciblent dev. La seule PR vers main est la PR de publication dev → 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.sh doit 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.

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.
  • DOUBLE PRECISION plutôt que NUMERIC pour les flottants. NUMERIC est mappé sur pgtype.Numeric dans 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 passez nil pour laisser la colonne intacte.
  • Régénérez avec ./scripts/generate.sh depuis la racine du dépôt après chaque modification de queries.sql ou de openapi.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 main queries.sql.go ni 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.sh les exécute sur une base <db>_test sé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.PanicShim partagé (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.
  • Les runes hors composants vont dans des modules .svelte.ts. Svelte 5 compile les runes ($state, $derived, $effect) dans les composants .svelte et dans les modules .svelte.js ou .svelte.ts ; dans un simple fichier .ts ou .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.ts est 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 web a les dépendances installées et monte votre répertoire web/ 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 avec npm ci dans web/ et lancez-y npm run check.
  • Régénérez le schéma d’API après toute modification de openapi.yaml : npm run generate:api depuis web/. 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 de openapi.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.sh copie en.json dans 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.log dans le code commité. Les instructions console ne sont que du bruit de débogage.

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.

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 .env créé par ./scripts/bootstrap.sh et de la stack Docker Compose déjà démarrée (docker compose up -d).
  • Exécute les tests Go sur une base <db>_test séparée dans le Postgres de cette stack, réinitialisée au début de chaque exécution. Dans un git worktree lié, 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=1 la conserve).
  • Laisse votre base de développement intacte.
  • Ne couvre que la suite Go. --with-s3 dé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.

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_*.sql au-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 up depuis 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.sql dans 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_node table » → é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 en external_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.

  • 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 / WithEmissionFn comme 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.PanicShim partagé. 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-verify sur 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-recreate pour 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.

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.