Documentation Conventions

Sistemas Solana falham quando docs vivem só no Slack: etapas de upgrade, docs de seeds PDA e runbooks de incidente devem viver em controle de versão ao lado de programas e clientes. Estas convenções alinham docs de engenharia com o formato deste guia SME.

Receita

Cartão de receita para referência rápida - pronto para copiar e colar.

docs/
  adr/           0001-title.md
  runbooks/      deploy-mainnet.md, incident-pause.md
  specs/         feature specs
packages/idl/
  lending.json   version in filename or package.json

Quando usar:

• Configurar novo monorepo
• Lista de documentação para auditoria
• Contribuir para esta base de conhecimento
• Item de ação pós-incidente "não tínhamos runbook"

Exemplo Prático

Cabeçalho ADR

# ADR 0007: Mainnet RPC provider selection
 
Status: Accepted | Supersedes: none | Review: 2026-12-01

Cabeçalho de runbook

# Runbook: deploy-mainnet.md
Owner: @alice | Backup: @bob | Last drill: 2026-05-15
 
## Prerequisites
- Squads signer 2-of-3 available
- CI artifact hash from release tag
 
## Steps
1. ...
 
## Rollback
solana program deploy --program-id ... ./artifacts/previous.so
 
## Verification
solana-verify get-program-hash ...

Publicação de IDL

anchor idl build -o packages/idl/lending-v2.4.0.json
# package.json "version": "2.4.0" matches program release

O que isso demonstra:

• Metadados ADR para rastreamento de ciclo de vida
• Owner, backup e data de drill no runbook
• Nome de arquivo IDL ou versão de pacote alinhada ao release

Aprofundamento

Tipos de documento

Footer de página SME

Toda página do guia autoria termina com blockquote de versões da stack conforme pipeline do site.

Erros comuns

• Runbooks em wiki - Obsoletos no incidente. Correção: Só git; PR review para mudanças.
• IDL não commitado - Builds de cliente desviam. Correção: Publicação CI na tag.
• ADR editado no lugar - Histórico perdido. Correção: Substitua com novo número.
• Só screenshots de explorer - Não reproduzível. Correção: Comandos CLI no runbook.
• Seeds PDA não documentadas - Bugs de derivação no cliente. Correção: Rustdoc em constantes de seed.

Alternativas

FAQs

Relacionados

• Architecture Decision Records (ADRs) - processo ADR
• Contribution Guidelines - quem atualiza o quê
• Coding & Program Standards - convenções de código

Versões da stack: Esta página foi 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 e LiteSVM 0.6.x.