cavioca

Contribuir

5 min

Contribuir

Cavioca es open source. El código vive en github.com/capitaharlock/cavioca y aceptamos contribuciones — desde correcciones de typos hasta features enteras. Esta página te lleva de un repo recién clonado a una PR abierta.

open El repo está en capitaharlock/cavioca. Si en el momento que lees esto el remote ha cambiado de nombre u organización, el README en la raíz tiene la versión definitiva.

Requisitos

  • Node ≥ 20 — declarado en engines del package.json raíz. Recomendado fnm o nvm para gestionar versiones.
  • npm — el repo usa npm workspaces, no pnpm ni yarn. Viene con Node.
  • git ≥ 2.30.
  • Una cuenta de Cloudflare sólo es necesaria si vas a desplegar; para desarrollo local no hace falta.

Arrancar local en una máquina limpia

# 1. clona el repo
git clone https://github.com/capitaharlock/cavioca.git
cd cavioca

# 2. instala dependencias (todos los workspaces a la vez)
npm install

# 3. arranca el front (apps/web) en http://localhost:3000
npm run dev --workspace=apps/web

# 4. en otra terminal, arranca la API (apps/api) en :8787
npm run dev --workspace=@cavioca/api

El front detecta automáticamente la API local cuando ambos corren. Si quieres configurar variables de entorno específicas, copia apps/web/.env.example a apps/web/.env.local (si existe) y edita lo necesario.

stub Datos de seed. No hay un script seed aún: arrancas con base vacía. Si vas a tocar funcionalidad que requiere usuarios, apps o waitlist, los creas a mano con wrangler d1 execute o desde la UI.

Lint y tests

Antes de abrir PR, lo mínimo:

# lint del workspace que has tocado
npm run lint --workspace=apps/web

# tests del backend
npm run test --workspace=@cavioca/api

CI corre estos comandos en cada push; las PRs con lint o tests rojos no mergean.

Convenciones

Commits

Usamos conventional commits. El tipo importa porque influye en cómo se construye el changelog:

feat(scope): qué hace
fix(scope): qué arregla
docs(scope): qué documenta
refactor(scope): qué reestructura sin cambiar comportamiento
chore(scope): tareas de mantenimiento

El scope suele ser el área tocada (web, api, docs, db). Ejemplos reales del repo:

feat(docs): DOC2 empezar section ES content + manifest
feat(api): waitlist endpoint + R2 binding
fix(web): edge runtime on /a/[slug]

Ramas

  • Trabaja sobre una rama corta desde main: feat/nombre-corto o fix/que-arregla. No hay rama dev permanente.
  • Mantén las PRs pequeñas y centradas. Una PR que toca front + API + migraciones a la vez es difícil de revisar; si puedes partirla, hazlo.

Estilo de código

  • TypeScript estricto en todo lo nuevo. Si tocas un fichero JS antiguo, añadir tipos al pasar es bienvenido pero no obligatorio.
  • Prettier está configurado a nivel de repo. Tu editor debería formatear al guardar; si no, npx prettier --write <archivo> antes del commit.
  • No introduzcas dependencias nuevas a la ligera. Cada npm install <pkg> añade superficie de mantenimiento. Si la nueva dep es necesaria, menciónalo en la descripción de la PR con el porqué.

Roadmap y dónde encajar

La roadmap pública vive en /about/roadmap — son las iniciativas activas y siguientes del cluster. Si quieres trabajar en algo ya planificado, busca una iniciativa abierta y comenta en el issue o manda un email a [email protected] antes de empezar para evitar trabajo duplicado.

Si tu idea no encaja en ninguna iniciativa existente, abre primero un issue describiéndola. Es más barato discutir el alcance antes de escribir el código que después.

Gobierno y MeshKore

El proceso de planificación, tareas y logs vive en .meshkore/ (parcialmente en el repo, parcialmente local). Está estructurado según el estándar MeshKore.

No necesitas entender MeshKore para contribuir código — los archivos .meshkore/public/ que verás en el repo son metadatos del cluster, no dependencias del producto. Si te interesa el proceso, el manual de operador en meshkore.com/cluster/operate es el punto de entrada.

¿Y la review?

Las PRs las revisa el mantenedor principal ([email protected]) y, donde toca infraestructura compartida, agentes especializados del cluster (deploy / db / security review). Tiempo de respuesta objetivo: 48 h laborables. open No hay aún un equipo de mantenedores distribuido; cuando lo haya, lo documentaremos aquí.

Gracias por contribuir.