Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
138 lines (100 loc) · 3.11 KB

CONTRIBUTING.md

File metadata and controls

138 lines (100 loc) · 3.11 KB

Contribuindo para SIRP Unified Bundle

Este documento fornece diretrizes para contribuir com o bundle SIRP Unified.

Estrutura do Projeto

sirp-unified/
├── packages/          # Pacotes originais preservados
├── spec/             # Especificações coladas (cópias)
├── docs/             # Documentação colada (cópias)
├── scripts/         # Scripts auxiliares
├── sirp.meta.json   # Manifesto com proveniência
└── Makefile         # Targets para demos/testes/benchmarks

Workflow Básico

1. Validação Antes de Commitar

Sempre rode o smoke test antes de fazer commit:

make smoke

Isso valida:

  • Estrutura do bundle
  • Consistência do sirp.meta.json
  • Existência de todos os caminhos referenciados
  • Validade dos schemas JSON
  • Permissões dos scripts

2. Adicionando um Novo Pacote

  1. Extraia o pacote em packages/<nome-do-pacote>/
  2. Atualize sirp.meta.json:
    • Adicione entrada em packages[]
    • Adicione entrada em inputs[] com SHA256 e tamanho
    • Atualize spec_index[] e docs_index[] se aplicável
  3. Valide: 
    make smoke
python3 scripts/sirp-validate.py

3. Atualizando Especificações/Documentação

  • Edite os originais em packages/<pacote>/
  • Cópias em spec/ e docs/ são apenas para conveniência
  • Se necessário, sincronize manualmente as cópias

4. Adicionando Scripts

  • Coloque scripts em scripts/
  • Garanta permissão de execução: chmod +x scripts/<script>
  • Documente no README.md

Convenções

Nomenclatura

  • Scripts: sirp-<nome>.sh ou sirp-<nome>.py
  • Pacotes: sirp-<nome>-<sufixo>
  • Versões: YYYY-MM-DD-rc<N> ou YYYY-MM-DD

Commits

Use mensagens descritivas:

feat: adiciona validação de schemas JSON
fix: corrige formatação de loops no Makefile
docs: atualiza README com novos comandos

Validação

Todos os scripts devem:

  • Ser executáveis
  • Ter shebang apropriado (#!/usr/bin/env bash ou #!/usr/bin/env python3)
  • Validar inputs quando aplicável
  • Retornar códigos de saída apropriados (0 = sucesso, != 0 = erro)

Testes

Testes do Bundle

# Smoke test completo
make smoke

# Validação estrutural
python3 scripts/sirp-validate.py

# Listar conteúdo
make list

# Ver metadata
make meta

Testes de Pacotes Individuais

# Testar sirp-node
cd packages/sirp-node-with-rfc/sirp-node
cargo test
make llm-check  # se integração LLM foi feita

Criando um Bundle

# Criar bundle zip
./scripts/sirp-bundle.sh

# Ou usar o target do Makefile (futuro)
# make bundle

Problemas Comuns

Erro: "package not found on disk"

  • Verifique que o pacote existe em packages/<nome>
  • Confirme que sirp.meta.json tem a entrada correta

Erro: "invalid JSON schema"

  • Valide o JSON manualmente: python3 -m json.tool <arquivo>
  • Verifique sintaxe JSON válida

Erro: "script not executable"

  • Adicione permissão: chmod +x scripts/<script>

Perguntas?

  • Consulte NEXT_STEPS.md para roadmap
  • Veja README.md para visão geral
  • Verifique sirp.meta.json para proveniência dos pacotes