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.json

Cuá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-01

Encabezado 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 programa

Lo 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

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

Preguntas Frecuentes

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.