Cómo contribuir

Aceptamos código, documentación, informes de errores y comentarios de cualquier persona dispuesta a presentarlos con claridad. Esta página cubre los aspectos prácticos: cómo lograr que un cambio sea incorporado, qué buscamos en la revisión y qué esperar después de abrir un PR.

Consulta Comunicación para contribuciones no relacionadas con el código (informar problemas, proporcionar comentarios, obtener ayuda).

Consulta el proceso de RFC para cambios más grandes que requieran discusión de diseño antes de la implementación.

Antes de comenzar

Para cualquier cosa que no sea una corrección de errata:

1. Consulta el rastreador de problemas. Alguien podría estar trabajando en ello o haber iniciado una discusión relacionada.
2. Lee AGENTS.md. La raíz del repositorio contiene el contrato compacto que siempre se carga. Usa las directrices para agentes de código para consultar referencias detalladas sobre riesgos, estabilidad, fuente de verdad y detección de habilidades.
3. Usa el Mapa de arquitectura y contribución para cualquier cosa relacionada con arquitectura, configuración, seguridad, flujo de trabajo, gobernanza, CI, comportamiento de lanzamiento o la política de contribución asistida por IA.
4. Selecciona una rama. Las PR se dirigen a master. Haz un fork del repositorio y crea una rama a partir de allí; no hay ninguna rama de desarrollo/integración que debas seguir.

El flujo

fork → branch → commit → push → open PR → review → merge (squash)

Los puntos clave:

• Plantilla de PR: .github/pull_request_template.md. Complétala. Las secciones de resumen, evidencia de pruebas y compatibilidad son innegociables.
• CI: se ejecuta en cada PR. ci.yml es la puerta de control compuesta; todas las etapas deben pasar.
• Etiquetas: los mantenedores usan etiquetas para dirigir la profundidad de la revisión. No necesitas conocer todas las familias de etiquetas antes de abrir un PR. Si las etiquetas parecen obviamente incorrectas y no puedes editarlas, señala la discrepancia en un comentario; los mantenedores o revisores con permisos de etiquetas pueden corregir las discrepancias obvias directamente.
• Enrutamiento de revisión: haga que el alcance, los issues vinculados, la validación y el contexto de riesgo/reversión sean lo suficientemente claros para que los revisores puedan elegir rápidamente la ruta de revisión adecuada.
• Revisión: revisión de los mantenedores. Los hallazgos utilizan la taxonomía de revisión de PR: 🔴 bloqueante, 🟡 advertencia, 🔵 sugerencia, 🟢 elogio y ✅ resuelto. Atienda los bloqueantes; las advertencias deben recibir una respuesta; las sugerencias son opcionales.

Estilo de código

• cargo fmt limpio (verificado en CI)
• cargo clippy -D warnings limpio (verificado en CI)
• Sin código de producción sin usar: elimínalo, intégralo en el comportamiento o registra un issue de seguimiento. No lo silencies con prefijos de guion bajo ni con #[allow(dead_code)]; reserva los nombres con guion bajo para parámetros de API, traits o callbacks que sean requeridos pero intencionalmente sin usar.
• Manejo de errores: anyhow::Result en los límites de binarios, errores tipados en crates de biblioteca. Sin unwrap() / expect() en rutas de código de producción: propague con ? o documente la invariante que hace imposible el panic.
• Dependencias mínimas: cada dependencia aumenta el tamaño del binario; evalúa la relación costo-beneficio antes de añadir una
• Primero el trait: define el trait en zeroclaw-api, luego impleméntalo en el edge crate correspondiente
• Seguridad por defecto: listas de permitidos, no listas de bloqueados. Las nuevas superficies externas se cierran por defecto
• Pruebas unitarias en línea: #[cfg(test)] mod tests {} al final del archivo o un archivo tests.rs hermano
• No haga commit de secretos, datos personales ni identidades de usuarios reales: la página Privacy & PII discipline es el requisito obligatorio para el merge

Comentarios y deriva

Los comentarios deben explicar la intención duradera, las invariantes, los riesgos o la propiedad del código fuente. No agregues comentarios que repitan el flujo de control cercano, dupliquen listas de campos de esquema o de configuración, reflejen variantes de enum ni describan comportamientos en tiempo de ejecución que el código y las pruebas no hagan cumplir. Esos comentarios se convierten en superficies de deriva: los futuros colaboradores y herramientas pueden confiar en la prosa después de que el código fuente haya cambiado.

Si un comentario necesita mencionar un comportamiento cuya responsabilidad está en otro lugar, remite al responsable en lugar de copiarlo. Prefiere comentarios que expliquen por qué una rama es segura, qué contrato es responsable de una regla o qué fuente debe cambiar primero.

Prefiere:

• El esquema de configuración gestiona los alias aceptados; mantén este resolver genérico.
• Este pánico es inalcanzable porque el analizador rechaza nombres de herramientas vacíos antes.

Evitar:

• Las variantes admitidas son A, B y C.
• Esta bandera siempre habilita la búsqueda vectorial.

Si la afirmación solo puede mantenerse verdadera editando manualmente el comentario cada vez que cambie el código, la configuración, WIT, el esquema o las pruebas, aclara la fuente o añade un puntero a la fuente en su lugar.

Pruebas

• Pruebas unitarias ubicadas junto al código (mod tests)
• Pruebas de integración en tests/ y pruebas unitarias locales del crate: se ejecutan mediante cargo nextest run --locked --workspace --exclude zeroclaw-desktop
• El código con características condicionales necesita pruebas con características condicionales
• No simules la base de datos en tests que ejercitan el esquema o SQL: los tests de integración deben usar una SQLite real

Para la taxonomía completa de cinco niveles (unidad / componente / integración / sistema / producción), la infraestructura compartida de simulación y el formato de fixture de trazas JSON, consulta Testing.

Cambios en la documentación

• Los cambios en el texto van en docs/book/src/**/*.md (este mdBook)
• Rustdoc (/ /) actualiza automáticamente la referencia de la API durante el despliegue.
• Las páginas de referencia (docs/book/src/reference/cli.md, config.md) son salidas generadas que se ignoran; no las edites ni las confirmes manualmente. Ejecuta cargo mdbook refs para previsualizar los cambios desde la fuente CLI/config correspondiente.
• Localización: El markdown en inglés es la fuente de verdad. Los PRs rutinarios de documentación en inglés pueden omitir cambios masivos generados en archivos .po; use la nota estándar del cuerpo del PR en Building the docs locally.
• Los PRs de caché de traducción, los pases de traducción de versiones y las nuevas configuraciones regionales deben ejecutar cargo mdbook sync, confirmar los archivos .po resultantes y validarlos con cargo mdbook check

Publicar metadatos del blog o sitio web

Cuando publiques una entrada de blog o actualices de algún otro modo los metadatos públicos del blog, actualiza las marcas de tiempo del feed mantenidas manualmente en el mismo PR:

• web/public/blog/rss.xml: establece <lastBuildDate> con la fecha de publicación más reciente de las entradas en formato RFC 2822 / GMT
• web/public/blog/atom.xml: establece <updated> con la hora de publicación de la entrada más reciente en formato ISO 8601 UTC
• web/public/sitemap.xml: establecer el <lastmod> de la entrada /blog a la fecha de publicación más reciente

Mantén el descubrimiento de feeds local al entorno:

• web/index.html debe mantener /blog/rss.xml, /blog/atom.xml y /sitemap.xml como enlaces relativos a la raíz
• web/public/sitemap.xml debería incluir la página /blog orientada al usuario, no los archivos de feed XML

Mensajes de confirmación

Conventional Commits:

feat(providers): add support for DeepSeek reasoning mode
fix(channels/matrix): prevent duplicate device sessions after verify
docs(getting-started): add YOLO-mode quick-start
refactor(runtime): split agent loop into steps
chore: bump tokio to 1.43

La colaboración asistida por IA es bienvenida, pero no añadas avisos de atribución a bots/IA ni pies de página de herramientas generadas al cuerpo de los PR o al final de los mensajes de commit. Los avisos Co-authored-by: de personas siguen siendo apropiados para el trabajo de colaboradores incorporado cuando cumplen las reglas de sustitución y privacidad. Consulta FND-005 (Contribution Culture) para conocer la norma completa.

Solicitudes de extracción

El título refleja el commit de squash:

feat(scope): short description

El cuerpo usa la plantilla del PR. La sección de pruebas es obligatoria: explica cómo se verificó el cambio y pega las comprobaciones que coincidan con el cambio. La receta A/B ejecutada por el revisor bajo How you can test solo es necesaria cuando la verificación manual aporta una señal útil; marca N/A para PRs solo de documentación, refactorizaciones puras o cambios triviales sin una ruta de prueba relevante para el revisor. Para PRs solo de documentación, usa scripts/ci/docs_quality_gate.sh y scripts/ci/docs_links_gate.sh o explica por qué la comprobación de enlaces no tenía enlaces nuevos que inspeccionar. Para PRs de Rust/código, usa la evidencia que coincida con la superficie modificada: comprobaciones CI requeridas, pruebas enfocadas del crate o de regresión, smoke tests manuales o comprobaciones completas del workspace cuando una cobertura amplia demuestre que una evidencia más estrecha pasaría por alto algo. La CI requerida reciente es suficiente cuando cubre la superficie modificada; no se requiere Cargo local adicional solo para duplicar el mismo head, target y conjunto de features. Añade más evidencia cuando el PR dependa de una brecha conocida de cobertura de CI: pruebas específicas de plataforma, lint multiplataforma, cobertura de la app de escritorio, builds de targets de release, CI desactualizada o CI no disponible. “It works on my machine” no es evidencia.

Las etiquetas de riesgo describen el cambio y la consecuencia reales, no su ámbito general. Sigue la guía de etiquetas para mantenedores: risk:low corresponde a documentación, fixtures o metadatos mecánicos sin ningún efecto en producción, compatibilidad, compilación, publicación o gobernanza; risk:medium corresponde al trabajo habitual de cambio de comportamiento; y risk:high corresponde a un límite concreto de confianza, credenciales, compatibilidad, gobernanza o autoridad de publicación. domain:security es independiente de risk:* e identifica un límite de seguridad efectivo.

Una PR que incluya risk:high o domain:security requiere una revisión exhaustiva, un plan de reversión adecuado al cambio y dos aprobaciones independientes del Core Team antes de la fusión. Usa risk:manual cuando un mantenedor necesite congelar futuras sustituciones automáticas del riesgo; no puede reducir el requisito de revisión.

Después del PR

Estrategia de fusión: squash-merge con el historial completo de commits preservado en el cuerpo. Consulta .claude/skills/squash-merge/SKILL.md para conocer el formato exacto: TL;DR: título del PR + (#number) como asunto, lista con viñetas de los commits originales como cuerpo.

Lanzamiento: los cambios se integran en master; master no se lanza automáticamente. Un mantenedor actualiza la versión y etiqueta vX.Y.Z cuando se publica una versión. Verás tu PR en el CHANGELOG.

Áreas que necesitan ayuda

Código de conducta

No seas grosero. Discrepa sobre las ideas, no sobre las personas. Acepta que los mantenedores cerrarán cosas que no quieren asumir, normalmente con una explicación, ocasionalmente sin ella. Si un cierre te parece injustificado, pregunta; si la pregunta no lleva a ninguna parte, sigue adelante.

Ver también

• Proceso de RFC: para cualquier cosa más grande que un parche
• Mapa de arquitectura y contribución: qué documentos de arquitectura, fundamentos y flujo de trabajo leer primero
• Comunicación: cómo contactar al equipo
• Maintainers → Información general: qué hacen los mantenedores en el día a día