[vitormattos]

Objetivo

Substituir a herança de diretórios versioned/base + versioned/shared.json por uma branch documental completa para cada versão do LibreSign, seguindo o modelo de contribuição do Nextcloud, sem perder URLs, guias, OpenAPI nem controles de publicação. Este PR também publica os guias dos webhooks nativos na documentação de desenvolvimento do LibreSign 16.

Como editar a documentação após a mudança

• Próxima versão: editar developer_manual/, admin_manual/ ou user_manual/ em main.
• Versões lançadas: editar os mesmos caminhos na branch stableNN, em que NN é a versão do LibreSign, não do Nextcloud.
• Nova página RST: incluir em seu .. toctree::. Nenhum teste Python por página, nenhum manifesto de caminhos nem duplicação em versioned/16/.
• Backports são explícitos e revisáveis. O botão Edit on GitHub de cada manual aponta para a branch da própria versão.

Branches já criadas e assinadas: stable13, stable14 e stable15.

Mudanças técnicas

1. versioning/sources.py: busca somente a branch documental correspondente a cada versão, preserva seu SHA e falha explicitamente caso a fonte estável esteja ausente.
2. versioning/build.py, verify.py e external_contract.py: mantêm a vinculação à OpenAPI exata da aplicação e verificam que o conteúdo documental foi consumido da mesma revisão da branch.
3. Remoção de versioned/base, versioned/shared.json e todas as sobreposições versioned/<major>/; redirecionamentos históricos preservados em versioning/legacy-routes.json.
4. Prévia navega no conteúdo real da branch de desenvolvimento, sem uma cópia artificial /_review/16/.
5. README, CONTRIBUTING.md, AGENTS.md e guia dos mantenedores apresentam um fluxo simples de contribuição. Os cinco guias de webhook e o Event Catalog ficam em main/developer_manual/webhooks/.

Validação

• Comparação da montagem antiga com a nova: mesmos 33 caminhos HTML por versão 13, 14 e 15, mesmos textos de conteúdo, links Edit on GitHub corrigidos.
• 37 testes Python e 12 JavaScript aprovados; Sphinx estrito aprovado em todas as versões.
• 163 páginas HTML verificadas, incluindo links, isolamento, redirecionamentos e proveniência OpenAPI.
• Exemplos de assinatura externa verificados contra todas as quatro revisões da aplicação; Bash, JSON e PHP 8.3 sem erros de sintaxe.
• Montagem e verificação do candidato de publicação sem deploy em produção.
• Rebase manual para main atual em quatro commits incrementais assinados, sem squash automático; o SHA da árvore final antes e depois é idêntico. O PR está mergeable, sem conflitos.
• Workflow Documentation aprovado para o último commit ee220f1.
• A primeira tentativa de preview encontrou um atraso de publicação do GitHub Pages: o workflow verificou HTML antigo antes de o deployment terminar. A correção ee220f1 aguarda a presença do versions.json exato no site antes de comparar as páginas. O workflow Documentation PR Preview passou no commit ee220f1, verificando o conteúdo servido pelo GitHub Pages. A transição de draft para Ready for review acionou uma segunda execução para o mesmo commit, ainda em curso.

Ordem de integração dos eventos

Os cinco eventos adicionais descritos no catálogo do LibreSign 16 ainda não existem na main da aplicação: a implementação está no LibreSign/libresign #9427, ainda aberto. Isso não deve aparecer como aviso dentro do manual versionado, mas é uma dependência de merge: integre o código dos eventos antes de publicar esta documentação como funcionalidade disponível. A remoção do callback legado é tratada separadamente no #9426.

O PR #130 está Ready for review, sem conflitos e com DCO aprovado; a aprovação obrigatória do code owner permanece para o mantenedor.

Acompanhamento das branches protegidas

As branches estáveis têm ruleset que exige PR e aprovação de code owner. Os READMEs e guias de manutenção que ainda descreviam a estrutura antiga foram atualizados em PRs específicos, todos com Sphinx e DCO aprovados: #138 (13), #139 (14) e #140 (15). Esses ajustes devem ser revisados e mergeados depois deste PR, sem contornar a proteção das branches.

Sem merge do PR #130, sem deploy do site de produção e sem merge dos três PRs dependentes.

[github-actions]

PR Preview Action v1.8.1-4-g2a6da11
🚀 View preview at https://libresign.github.io/site-preview/docs-preview/pr-130/
Built to branch gh-pages at 2026-11-09 14:23 UTC. Preview will be ready when the GitHub Pages deployment is complete.

[github-actions]

Navigable documentation preview

• All published versions
• LibreSign 16 development manual

This preview is isolated from production. Documentation for the next release lives in the development branch until it is released.