Pular para conteúdo

0004 — Documentação versionada por release

Status: Aprovado · Responsável: Gustavo Madruga · Atualizado em: 2026-06-24 · Decidido em: 2026-06-24

Contexto

O publish de docs sobrescrevia docs-sites/<app>/ a cada push — não havia como ver a doc "como era" numa versão passada. Queremos um seletor de versão no topo do site (nativo do MkDocs Material) e um snapshot imutável por release.

Decisão

Cada tag vX.Y.Z publica um snapshot da doc em docs-sites/<app>/<X.Y.Z>/; o site mostra a release de maior SemVer por padrão e um seletor lista as releases.

  • Layout do bucket — metadado e índice na RAIZ, só HTML por versão: <app>/{app.json, versions.json, index.html(redirect→maior SemVer), <X.Y.Z>/…, dev/…}. app.json fica na raiz (é metadado do app; movê-lo quebraria a fábrica de imagens, que lê */app.json, e o índice). Sem pasta latest/ — o alias vive no versions.json.

Correção 2026-06-26: "fica na raiz" precisava de um mecanismo, que faltou — a app.json chegava só em dev/ e o app caía em "Outros (sem app.json)" no portal (caso thoms-integracao-produto-ecom). Contrato explícito (em publicar-docs): app.json à raiz em TODO push (copyto aditivo); versions.json/index.html seguem release-only. - Seletor nativo do Material (extra.version.provider: mike): o spike (2026-06-24) provou na fonte que o Material busca ../versions.json relativo ao base e detecta a versão pelo último segmento — logo cada versão é buildada com site_url terminando na versão (.../aplicacoes/<app>/<X.Y.Z>/). - Gatilho: tag vX.Y.Z → snapshot <X.Y.Z>/ + regenera versions.json/index.html; master → dev/ (preview, fora do dropdown). Tag fora de X.Y.Z não versiona. - scripts/publica-versao.py (central, publicado no site) lista as versões do bucket e (re)escreve versions.json + index.html na raiz via rclone rcat (aditivo). NUNCA rclone sync da raiz <app>/ (apagaria todas as versões). - Forward-only: começa da próxima release; sem backfill. Migração: a raiz só vira redirect na 1ª release versionada (até lá serve o site flat antigo).

Alternativas consideradas

  • mike (ferramenta): automatiza isso, mas assume hosting em branch git (gh-pages); a casa hospeda por bucket. Replicar o resultado com rclone encaixa direto; o seletor é o mesmo (recurso do Material, não do mike). Preterido.
  • site_url fixo (sem a versão): o spike provou que o seletor furaria (busca o versions.json no nível errado). Preterido.

Consequências

  • Invariantes duros: app.json na raiz; nunca sync da raiz.
  • Portal central (dogfood): mecânica difere (build-na-imagem + nginx, não bucket) → diferido para a spec 012 (não trava os apps).
  • Storage cresce 1 snapshot/release — aceitável; admin/poda no portal é brief futuro.
  • Página "Mudanças" (CHANGELOG embutido) já existe → cada snapshot mostra o changelog daquela release de graça.