Pular para o conteúdo principal

Naming & Versioning Standard

Git preserva o histórico. O nome do arquivo não é lugar de versão, e "FINAL" não é versão.

1. Nomes de arquivo​

  • Arquivos em docs/: kebab-case, sem versão, sem data, sem status no nome.
    • ✅ governance-index.md, metodo-regua.md, docs-build.md
    • ❌ Governance_Index_FINAL.md, metodo-v2-corrigido.md, docs_build_latest.md
  • O nome do arquivo define a URL (slug). Por isso ele é estável: renomear quebra links — só renomeie com razão forte e corrija todos os links no mesmo commit.
  • O nome canônico do documento (ex.: 01_REGUA_OPERATING_SYSTEM_v1.0) vive no title/corpo, não no filename.

2. Palavras proibidas em nomes de arquivo​

Proibido em qualquer arquivo versionado da biblioteca (validado por npm run docs:check):

FINAL, final2, latest, corrected, corrigido, novo, new, copia, copy, backup, old, (1), (2)

Se você sente necessidade de escrever FINAL no nome, o que você quer é: incrementar a versão no frontmatter e commitar.

3. Versões​

  • Formato: MAJOR.MINOR[.PATCH] no frontmatter (version: "1.0", "1.1.2"), conforme o Document Lifecycle Standard §3:
    • MAJOR (v1.x → v2.0): mudança estrutural/incompatível. Exige revisão do owner.
    • MINOR (v1.1 → v1.2): mudança material/normativa aprovada.
    • PATCH (v1.1 → v1.1.1): alteração editorial/não-normativa em documento APPROVED.
  • Qualquer alteração de conteúdo em documento APPROVED recebe no mínimo PATCH bump (Lifecycle §3.1). Exceção única: metadata puramente operacional que não altera conteúdo publicado, regra, interpretação ou navegação — registrada apenas no Git.
  • Toda mudança de versão em documento APPROVED deve dizer no commit o que mudou.

4. Como o histórico funciona​

PerguntaResposta
Qual é a versão vigente?A que está em main (frontmatter version + status)
O que mudou entre versões?git log / git diff do arquivo
Como marcar um marco da biblioteca?Git tag (docs-v1.0)
Onde fica a versão antiga?No histórico do Git — nunca em arquivo paralelo

O versionamento nativo do Docusaurus está desativado por decisão: o site mostra somente a documentação vigente; o Git responde pelo passado.

5. Nomes de pastas​

As seções 00-… a 09-… têm prefixo numérico para ordenação estável. Não criar seções novas sem atualizar este standard.