Ir para o conteúdo

Contributing to Argus

Obrigado por contribuir. Este repositório é a biblioteca pública de observabilidade Argus.

English

Antes de abrir PR

  1. Abra uma issue pelo template (bug, feature, docs ou task). Issues em branco estão desligadas. Vulnerabilidade: SECURITY.md, não issue pública.
  2. Fork + branch a partir de main.
  3. Mantenha o diff focado — evite refactors não relacionados.
  4. Não inclua secrets, tokens ou referências a infra privada (hosts, stacks internas, domínios de produção).

Desenvolvimento

cp .env.example .env
docker compose up -d --build   # stack completa
go vet ./...
go test ./...                  # backend (Go 1.27+)
cd web && npm ci && npm run lint && npm test -- --run && npm run build   # painel (Node 24 LTS)
bash .github/scripts/check-no-vps-leak.sh   # opcional, local

CI e branch protection

O workflow .github/workflows/ci.yml roda em todo PR e push para main. Os jobs rodam em paralelo; um PR novo cancela a execução anterior do mesmo PR.

Job O que valida
changes Quais componentes mudaram no diff (ci-changes.sh)
anti-leak Padrões de infra privada no diff
gitleaks Secrets commitados: intervalo do PR, ou histórico completo no agendamento semanal
vuln-go govulncheck ./... (só CVE Go alcançável)
vuln-web npm audit --omit=dev --audit-level=high em web/
go go vet, go test, go build ./cmd/... — só se hub ou agent mudou
web npm ci, npm run lint, npm test -- --run, npm run build — só se web mudou
docker (hub/agent/web) Build do Dockerfile do componente que mudou (load: true), Trivy CRITICAL,HIGH (ignora unfixed), SARIF em Security
smoke Compose com essas imagens e um sidecar de log JSON; checklist pós-deploy
test Agregador: passa se nenhum job falhou (jobs pulados contam como ok)

Componentes por path:

Componente Paths
hub cmd/hub/, internal/ (exceto internal/agent/), go.mod, go.sum, Dockerfile.hub
agent cmd/agent/, internal/agent/, internal/model/, go.mod, go.sum, Dockerfile.agent
web web/

Mudança em ci.yml, ci-changes.sh ou nos arquivos de smoke, tag, workflow_dispatch, schedule ou branch nova sem base roda tudo.

O mesmo workflow também roda semanalmente (segunda) para CVE sem mudança de código falhar no Actions. O CodeQL (go e javascript-typescript) roda em todo PR e no agendamento semanal; alertas vão para Security → Code scanning.

O workflow Pages .github/workflows/pages.yml roda o check build site em todo PR (mkdocs build --strict). Push em main só faz deploy quando paths de docs mudam.

Branch protection em main: exigir pull request, os checks test e build site, branch atualizada, e bloquear force-push. Sem essas regras, merges podem ignorar o CI.

PRs empilhados: se main andou, ou o PR foi aberto contra uma feature, redirecione a base para main e faça rebase em main antes do merge. Não faça merge de PR cuja base é outra feature.

O Dependabot (.github/dependabot.yml) abre PRs agrupados semanais para GitHub Actions, módulos Go, npm (web/) e a imagem web. O CI roda nesses PRs como nos demais.

Alertas de dependência e imagem

Quando vuln-go, vuln-web ou Trivy falha:

  1. Atualize para uma versão com patch (go get, npm update ou imagem base mais nova) e rode o CI de novo.
  2. Se não houver patch, abra uma issue com o CVE, por que o risco é aceito e quando revisitar. Não ignore em silêncio sem issue.
  3. No npm, use overrides só num PR que cite essa issue. O govulncheck já ignora achados inalcançáveis; não desligue o job para esconder um alcançável.

Release (maintainers)

Escolher a versão

Siga semver. Enquanto a versão for 0.x, mudanças incompatíveis sobem o minor.

Mudança Bump Exemplo
Correção sem alterar contrato patch 0.1.0 → 0.1.1
Funcionalidade nova, rota ou env opcional minor 0.1.1 → 0.2.0
Rota removida/renomeada, payload incompatível, env obrigatória nova, schema de banco incompatível major (minor em 0.x) 1.4.2 → 2.0.0

Mudanças incompatíveis entram no CHANGELOG sob ### Breaking, com o passo de migração para quem atualiza.

Publicar

  1. Atualize CHANGELOG.md (seção [Unreleased] → [X.Y.Z] - data) e o link da versão no rodapé
  2. Commit e push em main
  3. Tag semver e push:
git tag v0.1.1
git push origin v0.1.1

O workflow .github/workflows/release.yml roda em etapas:

  1. verify tag — tag semver, commit presente em main e seção [X.Y.Z] no CHANGELOG. Falha aqui não publica nada.
  2. ci — o mesmo CI de PR, reutilizado (incluindo smoke).
  3. image (hub/agent/web) — Trivy numa imagem amd64 (CRITICAL,HIGH, ignora unfixed); depois build multi-arch (linux/amd64, linux/arm64) e push em paralelo para GHCR e Docker Hub, com SBOM e provenance. CVE crítica/alta corrigível bloqueia o push. Tags X.Y.Z, X.Y, X (a partir de 1.0), vX.Y.Z e latest.
  4. docker hub description — sincroniza README e descrição curta de cada repositório a partir de .github/dockerhub/.
  5. github release — notas extraídas do CHANGELOG.

Tags com sufixo (v0.2.0-rc.1) viram pre-release e não movem latest.

O Docker Hub usa os secrets DOCKERHUB_USERNAME e DOCKERHUB_TOKEN (token com permissão Read, Write, Delete) e a variável de repositório DOCKERHUB_NAMESPACE. Sem a variável (por exemplo, em forks), o release publica só no GHCR.

Smoke test pós-release:

docker compose -f examples/compose-minimal/docker-compose.published.yml pull
docker compose -f examples/compose-minimal/docker-compose.published.yml up -d
curl -s http://localhost:8080/health

Checklist

  • [ ] CI verde em main no commit da tag
  • [ ] Seção [X.Y.Z] no CHANGELOG com data e itens de [Unreleased] movidos
  • [ ] ### Breaking preenchido quando houver mudança incompatível
  • [ ] Novas variáveis em .env.example e docs/api/configuration.md
  • [ ] Workflow Release concluído e as três imagens com a tag X.Y.Z no GHCR e no Docker Hub
  • [ ] Smoke test acima com ARGUS_VERSION=X.Y.Z

Atualizar uma instância existente: docs/deploy.md.

Site de documentação

O site em harryraddatz.github.io/argus-observability é gerado pelo workflow .github/workflows/pages.yml com MkDocs a partir de docs/ (início em docs/index.md), CHANGELOG.md e CONTRIBUTING.md. Inglês é o idioma padrão; português usa o sufixo *.pt.md.

  • PR que toca esses arquivos roda mkdocs build --strict: link ou página quebrada falha o check.
  • Merge em main e cada release concluída publicam o site.
  • Página nova em docs/ precisa entrar no nav do mkdocs.yml.

Preview local:

pip install -r .github/pages/requirements.txt
mkdocs serve

Commits

Use mensagens convencionais curtas em inglês (feat:, fix:, docs:). O mesmo vale para título e corpo de PR e para entradas novas do CHANGELOG. Referencie issues no corpo quando aplicável (Closes #123). Docs canônicos e identificadores de API são em inglês; os arquivos em português são só tradução.

Pull requests

O GitHub preenche .github/pull_request_template.md (Why, What changes, How to validate, checklist). Vincule a issue (Closes #123). CI deve passar. Se alterar rotas API, contratos ou UI, atualize docs/api/ e docs/map.md.

Código

  • Go: siga o estilo existente no pacote tocado.
  • Web: React + shadcn/ui em web/ — componentes reutilizáveis em web/src/components/.
  • Testes: adicione ou ajuste _test.go para lógica de domínio alterada.

Conduta

Participantes seguem o CODE_OF_CONDUCT.md.