004-deploy-strategy¶

Metadado	Valor
Status	Aceito
Data	06-01-2026
Decisores	JGustavoCN
Contexto	DevOps & CI/CD

Resumo Executivo

Adoção de uma estratégia de Deploy Manual Controlado (via Makefile) para o GitHub Pages, em detrimento de uma automação total de CI/CD nesta fase. O objetivo é garantir que apenas versões estáveis e revisadas da documentação sejam publicadas, evitando a exposição de rascunhos ("Gatekeeper Strategy").

1. Contexto e Problema¶

O ciclo de vida da documentação do DataProfiler envolve edições frequentes, rascunhos de novas funcionalidades e seções incompletas ("Work in Progress").

A implementação de uma automação tradicional de CI/CD (ex: Deploy on Push na branch main) traria os seguintes riscos para este estágio inicial:

Exposição de Rascunhos: Publicação imediata de conteúdo incompleto ou não revisado.
Poluição do Histórico: Múltiplos deploys quebrados ou parciais no ambiente de produção (GitHub Pages).
Falta de Validação Local: Risco de publicar erros de formatação (Markdown/Mermaid) que não foram testados localmente pelo desenvolvedor.

2. Drivers da Decisão (Requisitos)¶

Controle de Qualidade: O deploy só deve ocorrer após validação explícita do desenvolvedor.
Simplicidade de Operação: O processo de publicação deve ser executado com um único comando, sem configurações complexas de pipeline.
Segurança: Evitar a publicação acidental de informações sensíveis ou funcionalidades não lançadas.
Independência de Infra: O processo deve funcionar sem depender de "runners" externos de CI/CD configurados.

3. Opções Consideradas¶

Opção A: CI/CD Automatizado (GitHub Actions)¶

Configuração de um workflow .yaml que dispara o build e deploy a cada push na branch main.

Prós

Zero Toque: Publicação contínua sem intervenção humana.
Padrão de Mercado: Prática comum em projetos maduros.

Contras

Risco de "Quebra em Produção": Se o commit tiver um erro de sintaxe, o site quebra publicamente.
Overhead de Configuração: Necessidade de gerenciar segredos e tokens no GitHub Actions.

Opção B: Deploy Manual Controlado (Gatekeeper) - ESCOLHIDA¶

Uso de scripts locais (Makefile) para compilar e publicar a documentação sob demanda.

Prós

Gatekeeper Humano: O desenvolvedor valida o site localmente (make docs) antes de decidir publicar.
Atomicidade: Garante que a versão publicada é exatamente a que foi testada na máquina do desenvolvedor.
Simplicidade: Implementação via comando simples do mkdocs encapsulado.

Contras

Fator Humano: O desenvolvedor pode esquecer de publicar após uma atualização importante.

4. Decisão¶

Foi selecionada a Opção B (Deploy Manual Controlado).

Justificativa Técnica¶

Nesta fase de estruturação massiva de conteúdo (550 páginas), a prioridade é a qualidade e integridade da informação publicada. A estratégia de Gatekeeper devolve o controle ao engenheiro, mitigando o risco de expor documentação "quebrada" ou incompleta. A automação total será reavaliada (ADR Futura) quando o projeto atingir maturidade estável.

graph TD
    A[Desenvolvedor] -->|1. make docs| B(Validação Local)
    B -->|Aprovado?| C{Decisão Humana}
    C -->|Sim| D[2. make docs-deploy]
    C -->|Não| E[Corrigir Rascunho]
    D --> F["GitHub Pages (Produção)"]

5. Consequências¶

Tipo	Descrição
Positivo	Garantia de que 100% dos deploys foram visualmente validados por um humano.
Positivo	Eliminação de custos e tempo de espera de filas de build em CI/CD.
Risco	Dessincronia temporária entre o código na `main` e o site publicado (se o dev esquecer o deploy).

6. Implementação Técnica¶

O comando é abstraído no Makefile para garantir a execução correta do script Python, forçando a atualização do histórico da branch de páginas.

# Publica no GitHub Pages forçando a sobrescrita do histórico (clean slate)
docs-deploy:
    @echo [DEPLOY] Publicando documentacao...
    python -m mkdocs gh-deploy --force