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.jsonQuando 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-01Cabeç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 releaseO 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
| Tipo | Local | Audiência |
|---|---|---|
| ADR | docs/adr/ | Engenharia, auditores |
| Runbook | docs/runbooks/ | On-call |
| Spec | docs/specs/ | PM + eng |
| IDL | packages/idl/ | Codegen de cliente |
| SME Guide | site/solana/ | Desenvolvedores |
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
| Alternativa | Use quando | Não use quando |
|---|---|---|
| Notion para specs | Preferência de PM | Único repositório de runbook |
| Rustdoc auto-gerado | Crates públicos | Runbooks |
| OpenAPI para API off-chain | Serviços REST | IDL on-chain |
FAQs
ADR vs RFC?
RFC propõe; RFC aceita vira ADR ou linka para ele.
Evidência de drill de runbook?
Data + link de ticket no cabeçalho do runbook após drill trimestral.
Docs em espanhol?
Inglês canônico no repo; overlays translate-es conforme pipeline do site.
Quem aprova PRs de doc?
Runbooks: owner ops; ADRs: tech lead; guia: qualquer sênior.
Mudança breaking no IDL?
Semver major; seção de migração nas release notes.
Diagramas?
Mermaid no git; export PNG opcional para slides.
Segredo em runbook?
Nunca; referencie só caminho de vault.
Pacote de doc para auditoria?
Índice ADR + diagrama de arquitetura + IDL + threat model.
Política de página obsoleta?
Data review-by no ADR; regen do guia em bump de versão da stack.
Link de guia de contribuidor?
Veja página de contribution guidelines na mesma seção.
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.