Ir al contenido

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.

  • main es solo para código estable: recibe únicamente puntos de control probados y funcionales procedentes de dev. Está prohibido hacer force-push a main. Está prohibido hacer push directamente a main sin un merge revisado previamente desde dev.
  • dev es la rama de integración. Las ramas de funcionalidad se fusionan en dev; dev fluye hacia main en los hitos de publicación.
  • feat/<scope>, fix/<scope>, chore/<scope> para las ramas de trabajo. Bórralas inmediatamente después del merge; solo dev y main son de larga duración.
  • 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.
  • Las PR de funcionalidades y correcciones apuntan a dev. La única PR hacia main es la PR de publicación dev → 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.sh debe 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.

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.
  • DOUBLE PRECISION en lugar de NUMERIC para los flotantes. NUMERIC se mapea a pgtype.Numeric en 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 pasa nil para dejar la columna como está.
  • Regenera con ./scripts/generate.sh desde la raíz del repositorio tras cada cambio en queries.sql o openapi.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 mano queries.sql.go ni 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.
  • 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.sh las ejecuta contra una base de datos <db>_test aparte 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.PanicShim compartido (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.
  • Las runas fuera de los componentes van en módulos .svelte.ts. Svelte 5 compila las runas ($state, $derived, $effect) en componentes .svelte y en módulos .svelte.js o .svelte.ts; en un archivo .ts o .js normal 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.ts es 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 web tiene las dependencias instaladas y monta tu directorio web/ en /app: docker compose exec -T web sh -c 'cd /app && npm run check'. Para ejecutarlo en el host, instala las dependencias bloqueadas con npm ci en web/ y ejecuta allí npm run check.
  • Regenera el esquema de la API tras cambiar openapi.yaml: npm run generate:api desde web/. El esquema está en gitignore, así que una copia desactualizada solo afecta a tus comprobaciones locales: la CI lo genera de nuevo a partir de openapi.yaml y 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.sh copia en.json al á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.log en el código confirmado. Las sentencias de consola son ruido de depuración.

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.

Ejecuta ./scripts/test.sh desde la raíz del repositorio y asegúrate de que pasa antes de cualquier push. El script:

  • Necesita el .env que crea ./scripts/bootstrap.sh y la pila de Docker Compose ya en marcha (docker compose up -d).
  • Ejecuta las pruebas de Go contra una base de datos <db>_test aparte en el Postgres de esa pila, reiniciada al comienzo de cada ejecución. En un git worktree enlazado, 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=1 la conserva).
  • Deja intacta tu base de datos de desarrollo.
  • Cubre solo la suite de Go. --with-s3 tambié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.

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_*.sql normales 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 up funcione 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.sql en 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_node table» → 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 a external_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.

  • 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 / WithEmissionFn como 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.PanicShim compartido. 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-verify en 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-recreate para 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.

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.