Convenciones de Documentación
Los sistemas de Solana fallan cuando la documentación vive solo en Slack: los pasos de actualización, la documentación de semillas de PDA y los runbooks de incidentes deben vivir en control de versiones junto a los programas y clientes. Estas convenciones alinean la documentación de ingeniería con este formato de guía de SME.
Receta
Tarjeta de referencia rápida - lista para copiar y pegar.
docs/
adr/ 0001-title.md
runbooks/ deploy-mainnet.md, incident-pause.md
specs/ especificaciones de características
packages/idl/
lending.json versión en el nombre del archivo o package.jsonCuándo usar esto:
- Configuración de un nuevo monorepo
- Lista de solicitudes de auditoría de documentación
- Contribución a esta base de conocimiento
- Elemento de acción post-incidente "no teníamos un runbook"
Ejemplo de Trabajo
Encabezado de ADR
# ADR 0007: Selección del proveedor RPC de Mainnet
Estado: Aceptado | Reemplaza: ninguno | Revisión: 2026-12-01Encabezado de Runbook
# Runbook: deploy-mainnet.md
Propietario: @alice | Respaldo: @bob | Último simulacro: 2026-05-15
## Prerrequisitos
- Firma de escuadrones 2 de 3 disponible
- Hash del artefacto CI de la etiqueta de lanzamiento
## Pasos
1. ...
## Rollback
solana program deploy --program-id ... ./artifacts/previous.so
## Verificación
solana-verify get-program-hash ...Publicación de IDL
anchor idl build -o packages/idl/lending-v2.4.0.json
# La versión "version": "2.4.0" de package.json coincide con la etiqueta de lanzamiento del programaLo que esto demuestra:
- Metadatos de ADR para el seguimiento del ciclo de vida
- Propietario del runbook, respaldo, fecha del simulacro
- Nombre de archivo de IDL o versión del paquete alineado con el lanzamiento
Inmersión Profunda
Tipos de Documentos
| Tipo | Ubicación | Audiencia |
|---|---|---|
| ADR | docs/adr/ | Ingeniería, auditores |
| Runbook | docs/runbooks/ | De guardia |
| Especificación | docs/specs/ | PM + eng |
| IDL | packages/idl/ | Generación de código de cliente |
| Guía SME | site/solana/ | Desarrolladores |
Pie de Página de Página SME
Cada página de guía redactada termina con un bloque de citas de versiones de stack por el pipeline del sitio.
Trampas
- Runbooks de Wiki - Obsoletos durante un incidente. Solución: Solo Git; revisión de PR para cambios.
- IDL no confirmado - Las compilaciones de clientes se desvían. Solución: Publicación de CI en la etiqueta.
- ADR editado en el lugar - Se pierde el historial. Solución: Reemplazar con un nuevo número.
- Solo capturas de pantalla del explorador - No reproducibles. Solución: Comandos CLI en el runbook.
- Semillas de PDA no documentadas - Errores de derivación del cliente. Solución: Rustdoc en constantes de semillas.
Alternativas
| Alternativa | Usar Cuando | No Usar Cuando |
|---|---|---|
| Notion para especificaciones | Preferencia del PM | Único almacén de runbooks |
| Rustdoc autogenerado | Crates públicos | Runbooks |
| OpenAPI para API fuera de cadena | Servicios REST | IDL en cadena |
Preguntas Frecuentes
¿ADR vs RFC?
RFC propone; RFC aceptado se convierte en ADR o enlaza a él.
¿Evidencia de simulacro de runbook?
Fecha + enlace de ticket en el encabezado del runbook después del simulacro trimestral.
¿Documentos en español?
Canónico en inglés en el repositorio; superposiciones de translate-es según el pipeline del sitio.
¿Quién aprueba los PRs de documentación?
Runbooks: propietario de ops; ADRs: líder técnico; guía: cualquier persona senior.
¿Cambio que rompe IDL?
Semver mayor; sección de migración en notas de lanzamiento.
¿Diagramas?
Mermaid en git; exportar PNG opcional para diapositivas.
¿Secreto en runbook?
Nunca; solo referenciar la ruta de la bóveda.
¿Paquete de documentación de auditoría?
Índice ADR + diagrama de arquitectura + IDL + modelo de amenazas.
¿Política de página obsoleta?
Fecha de revisión en ADR; regeneración de guía al aumentar la versión del stack.
¿Enlace a la guía del contribuyente?
Ver la página de directrices de contribución en la misma sección.
Relacionado
- Registros de Decisiones de Arquitectura (ADRs) - Proceso ADR
- Directrices de Contribución - quién actualiza qué
- Estándares de Código y Programas - convenciones de código
Versiones de Stack: Esta página fue escrita para Agave 4.1.1, Solana CLI 3.0.10, Anchor 0.32.1, anchor-lang 0.32.1, Rust 1.91.1, @solana/kit 7.0.0, Surfpool 0.12.0, y LiteSVM 0.6.x.