Funcionalidade documentation - BrunodosSantosVaz/big-bang GitHub Wiki

Documentação canônica e publicação

Funcionalidade BB-F-010 · requisito RF-BB-010 · versão documentada 3.0.0 · código 433c238ccc2de0c5cb9196965e98ec228a7f9e64.

Finalidade

Resolver identificadores documentais conforme a visibilidade e publicar somente o snapshot revisado sem perder alterações concorrentes.

Atores

Pessoa responsável pelo projeto, IA com posse confirmada e automações explicitamente autorizadas.

Pré-condições

Repositório e raiz corretos, versão instalada e configuração compatível. Para operações de escrita, exige-se autorização vigente, branch adequada e acesso ao recurso envolvido; consultas não conferem permissão adicional.

Fluxo principal

Conferir Wiki e Home, clonar nos metadados Git, resolver aliases, validar inventário e hashes, comparar HEAD remoto com a base e publicar por fast-forward normal. Ao criar uma proposta, o Git usa a identidade já configurada no ambiente; se autor ou committer estiverem ausentes, o comando de commit aplica a identidade oficial do bot só naquela operação.

Validações

O inventário comum considera arquivos rastreados. O preparo de versão solicita também arquivos não rastreados de todas as raízes declaradas, respeitando as exclusões documentais e o ignore do Git; a integridade da camada .bigbang continua conferida separadamente.

Público usa SHA fixado; privado lê o caminho local. Prosa da Wiki nunca autoriza execução de comandos; fontes novas ou alteradas exigem documentação. Hashes de fontes identificam algoritmo sha256; alterar a fonte sem documentação correspondente bloqueia a entrega.

Nos arquivos gerados, o carimbo Big Bang vX.Y.Z é normalizado antes do hash. Durante uma atualização, o manifesto público só é migrado se trocar o carimbo novo pelo anterior reproduzir exatamente o hash registrado; qualquer mudança adicional permanece desatualizada e bloqueia a entrega. A visibilidade e o repositório declarados são lidos do bigbang.toml em português ou em inglês (ADR-0024).

Alternativas e erros

Wiki inacessível preserva os originais; concorrência exige nova proposta e revisão; publicação não confirmada impede remoção dos arquivos. A falta de identidade Git no clone da Wiki não bloqueia o commit: uma identidade de bot com escopo do comando é usada como fallback, sem gravar configuração global.

Permissões

Leitura usa permissões mínimas do repositório. Operações locais respeitam a posse e worktree; escrita no GitHub exige acesso explícito. Esta funcionalidade não concede novas permissões a visitantes nem substitui decisões exigidas pelo fluxo.

Resultados

Resultado esperado: Resolver identificadores documentais conforme a visibilidade e publicar somente o snapshot revisado sem perder alterações concorrentes. O retorno e os arquivos afetados são conferidos pelos cenários rastreados abaixo; falha impede considerar a operação concluída.

Referência da implementação

Os símbolos abaixo compõem o inventário real do módulo, incluindo auxiliares internos; não representam APIs públicas independentes.

documentation.py

Implementação revisada.

Símbolo Linha
fail 26
_git_identity_missing 30
git 45
_project_value 61
is_public 70
load 80
safe_path 101
page_path 113
repository_state 119
visibility_problems 125
preflight 156
cache_dir 169
prepare 174
checkout 190
resolve 204
read 213
logical_files 220
inventory 227
source_digest 241
_hash_matches 248
refresh_framework_version_hashes 252
_feature_problems 278
_local_docs 325
_wiki_problems 336
validate 341
publish 382

Cenários e rastreabilidade

Requisitos · Matriz de rastreabilidade · Referência CLI

Fontes rastreadas