Manifesto numeração e mapa geral
Nesta aula
Identidade não é posição
O manifesto é o mapa dos artefatos que o projeto reconhece como oficiais, candidatos ou históricos. Ele responde qual documento orienta o trabalho e onde localizar sua versão. Um número pode facilitar referência, mas não prova vigência. O documento 003 pode estar superado, enquanto uma revisão posterior do mesmo documento ocupa o papel vigente.
Identificador é o nome estável de uma entidade; versão identifica uma revisão; estado informa seu papel atual. Separar essas três dimensões evita renumerar todo o acervo quando se insere um documento. No código, nomes por responsabilidade continuam mais úteis que uma sequência arbitrária: catalogo.mjs informa a finalidade; 017.mjs exige consulta adicional.
A Oficina Caracol não precisa numerar cada arquivo para ser organizada. Precisa saber qual contrato e qual gate sustentam a versão entregue. S07, nas seções sobre registro de alterações e histórico, oferece mecanismos para localizar revisões. O manifesto acrescenta a decisão sobre seu papel; um commit antigo não é automaticamente o documento vigente.
Manifesto preenchido em um exercício
Considere cinco artefatos documentais. Os rótulos r1 e r2 abaixo são revisões lógicas do exercício, não identificadores de commits executados. Em um repositório real, cada rótulo deve corresponder a uma revisão recuperável e verificável; se essa associação não existe, a rastreabilidade ainda está incompleta.
| Identificador | Caminho de referência | Revisão | Estado e relação |
|---|---|---|---|
| DOC-DEC-01 | pratica/docs/decisao-001.md | r1 | Vigente; decisão de não usar dependências externas |
| DOC-EVI-01 | pratica/docs/evidencia-001.md | r1 | Vigente como plano; execução pendente deve continuar explícita |
| DOC-GATE-01 | pratica/docs/gate-001.md | r1 | Vigente; bloqueia liberação até resultados necessários |
| DOC-GATE-01 | pratica/docs/gate-001.md | r2 | Candidata; substituirá r1 somente após decisão |
| DOC-RISCO-01 | pratica/docs/risco.md | r1 | Vigente; riscos e responsáveis do incremento |
As duas linhas do gate não significam duas autorizações vigentes. r2 é candidata. Enquanto a decisão de substituição não ocorrer, r1 continua orientando o avanço. A implementação do armazenamento pode usar histórico de versões ou um arquivo candidato separado; a relação precisa ser recuperável. O manifesto não deve apontar duas revisões diferentes como se ocupassem simultaneamente o mesmo papel.
Quando r2 for aprovada, registre quem decidiu, qual evidência sustenta a revisão e quando ela passa a valer. Marque r1 como histórica e substituída por r2. Preserve o identificador DOC-GATE-01, pois o objeto continua sendo o registro de gate; uma nova revisão não precisa adquirir uma identidade sem relação com a anterior.
Procedimento de manutenção
- Defina quais artefatos precisam de controle explícito; não inclua cada arquivo por reflexo.
- Atribua identificadores estáveis e nomes que expressem finalidade.
- Registre caminho, revisão, estado, responsável e relação de substituição quando existir.
- Ao aprovar uma substituição, atualize estados e referências de forma conjunta.
- Confira se uma pessoa consegue abrir a revisão indicada e distinguir plano de evidência executada.
Erros e reparos específicos
| Erro | Reparo |
|---|---|
| Renumerar todo o histórico ao inserir um item | Preservar IDs e acrescentar o novo sem alterar referências antigas |
| Número sem estado | Adicionar vigência e relação de substituição |
| Arquivo chamado final-final sem revisão recuperável | Adotar identificador estável e revisão verificável |
| Candidato tratado como vigente | Registrar aprovação ou manter o bloqueio anterior até a decisão |
Exercício e solução
Dados: DOC-GATE-01 r1 está vigente e bloqueado. r2 foi escrita, mas depende de verificação manual ainda não realizada. Alguém quer apagar r1 e chamar r2 de aprovada porque ela é mais recente. Atualize o manifesto de maneira correta.
Ver solução comentada
Solução: manter r1 vigente e bloqueada; conservar r2 candidata, com a pendência de verificação explícita. Não apagar a revisão anterior. A data mais recente não substitui a evidência exigida. Depois da verificação aceitável e da decisão da autoridade, r2 pode tornar-se vigente e r1 histórica, com vínculo de substituição.
- Rubrica: preservar identidade e histórico, diferenciar revisão e estado, impedir promoção automática pela data e indicar o gatilho legítimo de substituição.
- Gate: todos os artefatos controlados têm revisão recuperável e estado inequívoco; existe apenas uma revisão vigente por papel e escopo. Links inexistentes ou candidatos apresentados como oficiais impedem a passagem.
Fontes relacionadas
Consulte os limites e as seções de apoio de cada referência.
S07 S03Tente o exercício antes de consultar a solução. Marque a aula para organizar sua leitura.
A conclusão desta leitura não equivale a certificação ou aceite de um projeto real. Teste os exemplos no escopo indicado e registre as limitações.