Estándares de código
Las convenciones que siguen existen para que los colaboradores no tengan que deducirlas de nuevo en cada PR y para que el código siga siendo legible a medida que crece.
maines solo para código estable: recibe únicamente puntos de control probados y funcionales procedentes dedev. Está prohibido hacer force-push amain. Está prohibido hacer push directamente amainsin un merge revisado previamente desdedev.deves la rama de integración. Las ramas de funcionalidad se fusionan endev;devfluye haciamainen los hitos de publicación.feat/<scope>,fix/<scope>,chore/<scope>para las ramas de trabajo. Bórralas inmediatamente después del merge; solodevymainson de larga duración.
Commits
Sección titulada «Commits»- Formato:
<area>: <imperative summary>. Por ejemplo:assets: handle 0-byte uploads,web: fix viewer crash on EXR with no exif. - Un cambio lógico por commit. Si un refactor y una corrección llegaron juntos, sepáralos.
- Sin líneas de coautoría de Claude / IA. El cambio es del colaborador.
- Indica el número de issue/PR en el cuerpo, no en el asunto.
- Usa HEREDOC para los mensajes de commit de varias líneas: conserva el formato a través de los shells.
Pull requests
Sección titulada «Pull requests»- Las PR de funcionalidades y correcciones apuntan a
dev. La única PR haciamaines la PR de publicacióndev → main, que se abre como parte del proceso de release (RELEASING.md). - La descripción de la PR explica por qué, no qué. El diff ya muestra el qué.
- Referencia el ADR relevante (
See ADR 0036) y cualquier issue relacionada. ./scripts/test.shdebe pasar en local antes de abrir la PR. La CI lo vuelve a ejecutar; una CI en rojo bloquea.- Squash-merge para las ramas de funcionalidad; merge commit para la publicación
dev → main.
Estilo de Go
Sección titulada «Estilo de Go»Las reglas no obvias. La CI exige el formato con gofmt (el job falla si gofmt -l lista algún archivo bajo app/) y no ejecuta ningún otro linter de Go.
- Los errores se devuelven. Nada de tragarse errores en silencio, nada de
_ = err. Si de verdad es seguro ignorar un error, escribe un comentario que diga por qué. - Confía en el código interno, valida en las fronteras. No revalides entradas que tus propios llamadores ya validaron. Sí valida en los puntos de entrada HTTP (funciones handler) y en los puntos de entrada de sistemas externos (backends de almacenamiento, conectores).
- Sin comprobaciones defensivas de nil sobre valores que nunca son nil. Si el sistema de tipos o el framework garantiza que un valor no es nil, no añadas una comprobación que «no puede dispararse»; hace que el lector dude de la garantía.
- Los comentarios explican el porqué, no el qué. El código que se lee como código no necesita narración; el código con una restricción oculta, un workaround o un invariante no obvio, sí.
- Mantén cortos los comentarios de documentación. Una o dos líneas suelen bastar para un símbolo exportado; quien lee godoc es un ingeniero que ya conoce Go. Escribe más cuando los llamadores lo necesiten: un contrato no obvio, una restricción de seguridad, el comportamiento de concurrencia o un invariante, como el comportamiento del bloqueo consultivo (advisory lock) documentado en
db.Migrate. - Organización por dominio. Cada dominio es dueño de su directorio
internal/<domain>/. Las llamadas entre dominios pasan por la capa de handlers o por pequeñas interfaces inyectadas como dependencia, nunca accediendo directamente al repositorio de otro dominio.
sqlc + pgx
Sección titulada «sqlc + pgx»- DOUBLE PRECISION en lugar de NUMERIC para los flotantes. NUMERIC se mapea a
pgtype.Numericen pgx, que es incómodo de manejar desde Go. - El patrón PATCH con COALESCE para actualizaciones parciales:
UPDATE foo SET col = COALESCE(sqlc.narg('col'), col), y pasanilpara dejar la columna como está. - Regenera con
./scripts/generate.shdesde la raíz del repositorio tras cada cambio enqueries.sqloopenapi.yaml. Los pasos de sqlc y oapi-codegen se ejecutan en contenedores; el script también usa utilidades de shell del host para regenerar el PanicShim compartido. No edites a manoqueries.sql.goni ningún otro archivo generado. - La CI comprueba que el código generado no esté desactualizado. El job de deriva del código generado regenera el código Go y falla si el resultado difiere de lo que has confirmado. Si falla, vuelve a ejecutar
./scripts/generate.sh, revisa el diff y haz commit.
Pruebas
Sección titulada «Pruebas»- Las pruebas de integración usan un Postgres real. Sin mocks de base de datos. La divergencia entre mock y producción ya nos ha jugado una mala pasada; el script de pruebas (
./scripts/test.sh) ejecuta cada prueba contra una base de datos desechable en el Postgres de la pila de Docker Compose. - Las pruebas nunca tocan tu base de datos de desarrollo.
./scripts/test.shlas ejecuta contra una base de datos<db>_testaparte que reinicia al comienzo de cada ejecución, así que tu cuenta de administrador y tus datos no se ven afectados. - Los shims de prueba del servidor estricto de OpenAPI embeben el
strictservershim.PanicShimcompartido (consulta «Lo que no hacemos» más abajo), de modo que una operación nueva no necesita un stub propio por paquete. - Sin mocks para aserciones del tipo «¿se llama realmente a esto?». Si quieres comprobar que se llamó a una función, refactoriza para que el efecto secundario sea observable (una fila en una tabla, un trabajo en una cola) y prueba ese efecto secundario.
Estilo del frontend (Svelte 5)
Sección titulada «Estilo del frontend (Svelte 5)»- Las runas fuera de los componentes van en módulos
.svelte.ts. Svelte 5 compila las runas ($state,$derived,$effect) en componentes.sveltey en módulos.svelte.jso.svelte.ts; en un archivo.tso.jsnormal no se compilan, por lo que el código no se comportará como se espera. Svelte acepta cualquiera de las dos extensiones de módulo;.svelte.tses la convención de este proyecto, coherente con su base de código en TypeScript. web/src/lib/components/es el conjunto de componentes compartidos. Los componentes propios de una ruta viven junto a la ruta a la que pertenecen.- Comprueba los tipos antes de hacer push. Con la pila de Compose en marcha, el contenedor
webtiene las dependencias instaladas y monta tu directorioweb/en/app:docker compose exec -T web sh -c 'cd /app && npm run check'. Para ejecutarlo en el host, instala las dependencias bloqueadas connpm cienweb/y ejecuta allínpm run check. - Regenera el esquema de la API tras cambiar
openapi.yaml:npm run generate:apidesdeweb/. El esquema está en gitignore, así que una copia desactualizada solo afecta a tus comprobaciones locales: la CI lo genera de nuevo a partir deopenapi.yamly después ejecuta svelte-check, vitest y una compilación de vite. El lado Go de la API se genera por separado, con./scripts/generate.sh. - Las cadenas i18n viven en
web/src/lib/i18n/<locale>.json. Las superficies nuevas añaden la clave en inglés; los borradores de los demás idiomas vienen después../scripts/generate.shcopiaen.jsonal árbol de Go, así que vuelve a ejecutarlo tras cambiar las cadenas en inglés o la comprobación de deriva de la CI fallará. - Sin
console.logen el código confirmado. Las sentencias de consola son ruido de depuración.
Comentarios
Sección titulada «Comentarios»Por defecto, sin comentario. Añade uno solo cuando el PORQUÉ no sea obvio: una restricción oculta, un invariante sutil, un workaround para un bug concreto, un comportamiento que sorprendería a un lector.
Lo que no hay que escribir:
- Lo que hace el código: los identificadores bien nombrados ya lo dicen.
- Referencias a la tarea / corrección / llamadores del momento («usado por X», «añadido para el flujo Y», «gestiona el caso de la issue #123»): eso va en la descripción de la PR y se pudre en el código.
- Comentarios de varios párrafos: si algo necesita tres párrafos para explicarse, probablemente necesita un ADR.
Prueba en local antes de hacer push
Sección titulada «Prueba en local antes de hacer push»Ejecuta ./scripts/test.sh desde la raíz del repositorio y asegúrate de que pasa antes de cualquier push. El script:
- Necesita el
.envque crea./scripts/bootstrap.shy la pila de Docker Compose ya en marcha (docker compose up -d). - Ejecuta las pruebas de Go contra una base de datos
<db>_testaparte en el Postgres de esa pila, reiniciada al comienzo de cada ejecución. En ungit worktreeenlazado, el nombre de la base de datos recibe un hash corto de la ruta del checkout, y esa base de datos se elimina al terminar la ejecución (AA_TEST_KEEP_DB=1la conserva). - Deja intacta tu base de datos de desarrollo.
- Cubre solo la suite de Go.
--with-s3también arranca MinIO y ejecuta las pruebas del almacenamiento S3.
Las comprobaciones del frontend van aparte: npm run check, npm test (vitest) y npm run build, desde web/ o en el contenedor web.
La CI cubre más que el script local. El job de integración ejecuta ./scripts/test.sh sobre una pila recién construida; otros jobs comprueban gofmt, regeneran el código y fallan si hay deriva, y ejecutan la comprobación de tipos, las pruebas unitarias y la compilación del frontend. Las pull requests que solo cambian documentación se saltan estos jobs. Ejecutar antes en local los pasos equivalentes suele ahorrar una ida y vuelta.
Migraciones de base de datos
Sección titulada «Migraciones de base de datos»Las migraciones viven en app/internal/db/migrations/ como archivos NNNNN_*.sql gestionados por goose. app/schema.sql es un volcado solo del esquema de una base de datos construida ejecutando las migraciones; sqlc lee ese archivo, no las migraciones, cuando genera código.
- Durante la beta (antes de la v1.0.0): las migraciones nuevas se añaden como archivos
NNNNN_*.sqlnormales sobre la base de referencia v0.1.0, según el ADR 0046. Se volverán a fusionar en una nueva base de referencia con el tag v1.0.0. Las instalaciones existentes se actualizan ejecutando las migraciones añadidas, algo que ocurre automáticamente al arrancar. - Después de la v1.0: solo hacia delante, para siempre. Se acabaron los squashes. Operadores reales con datos reales dependen de que
goose upfuncione desde cualquier versión publicada anteriormente. - Las restricciones CHECK reflejan constantes de Go tipadas, según el ADR 0042. Cuando la migración impone un conjunto cerrado en la capa de base de datos, ese mismo conjunto existe como constantes tipadas en el paquete propietario; ambas mitades llegan en la misma PR.
- Regenera
app/schema.sqlen el mismo commit que añade una migración (la cabecera del archivo indica los pasos); no lo edites a mano. La CI no lo compara con las migraciones, así que quienes revisan comprueban que ambos concuerdan.
Sin comparaciones de productos en el código fuente
Sección titulada «Sin comparaciones de productos en el código fuente»El código fuente (Go, Svelte, comentarios SQL, OpenAPI) no debe apoyarse en comparaciones nombradas con productos de la competencia o de inspiración. Las comparaciones nombradas envejecen mal cuando el producto cambia y confunden a quien no sabe qué significa «AFFiNE-shaped».
En la práctica:
- No escribas «Mastodon-shaped activity dispatch» → escribe «ArchivePub activity dispatch».
- No escribas «the prior generation’s
resource_nodetable» → expón el diseño por sí mismo. - No escribas «AFFiNE’s element-typed model» → escribe «an element-typed model».
- No escribas «Frame.io-style timestamped comments» → escribe «asset-anchored timestamped comments».
- No escribas «PeerTube has to move every byte» → elimina la comparación; describe simplemente lo que hacemos.
- No conserves los nombres de columna
rs_user_id/rs_resource_id; renómbralos aexternal_user_id, que es neutral, o elimínalos si la columna ya no se usa.
Excepciones. Dos lugares conservan intencionadamente referencias nombradas a productos originales o de la competencia:
- Los ADR y
docs/research/: documentos de decisión y registro histórico. - Las superficies de atribución de licencias: avisos de dependencias de terceros exigidos por sus licencias (reconocer una fuente no es comparar). La antigua atribución de la base del fork de ResourceSpace se eliminó una vez borrado el código derivado de RS y relicenciado el proyecto bajo AGPL-3.0 (ADR 0001 → sustituido por el ADR 0040).
Todo lo demás del código fuente se mantiene neutral.
Lo que no hacemos
Sección titulada «Lo que no hacemos»- Shims de retrocompatibilidad para código del que no depende ningún llamador real. Si renombras una función y nada real usaba el nombre antiguo, borra el nombre antiguo. No conserves zombis «por compatibilidad».
- Rutas de respaldo heredadas en handlers ya conectados. Según el ADR 0044, todo handler que emite actividades de federación usa
WithEmission/WithEmissionFncomo su único camino de código. El patrón «si el writer de actividades no está conectado, recurrir a la escritura del dominio» está prohibido: en producción nunca se activa; en las pruebas oculta el invariante de corrección de la entrega federada. Las pruebas conectan el writer de actividades en su setup; no hay un segundo camino. - Stubs de prueba que proliferan por paquete. Las pruebas del servidor estricto de OpenAPI usan el
internal/openapi/strictservershim.PanicShimcompartido. Embébelo; sobrescribe solo los métodos que la prueba ejercita de verdad. No crees un nuevo archivo de shim por paquete con N métodos que hacen panic cada vez que llega una operación de OpenAPI. - Abstracciones especulativas. Tres líneas parecidas son mejores que una abstracción prematura para dos. El tercer llamador justifica el helper; el segundo no.
--no-verifyen los commits. El repositorio no incluye ningún hook de Git, pero si ejecutas los tuyos, no los esquives: si un hook falla, arregla el problema de fondo.- Workarounds con
--force-recreatepara contenedores obsoletos en rutas de producción. Está bien en desarrollo local cuando los cambios del binario de Go no se recogen; producción tiene otras reglas de ciclo de vida.
En caso de duda
Sección titulada «En caso de duda»Lee las PR fusionadas recientemente para ver cómo escribe código la base actual de colaboradores. Consulta el ADR de convenciones (0035) para las pautas de documentación. Si la respuesta sigue sin estar clara, pregunta en la PR o en una issue; el responsable del proyecto prefiere responder una vez a desenredar diez patrones divergentes más tarde.