Funcionalidade fluxo agrupador - BrunodosSantosVaz/big-bang GitHub Wiki

Fluxo agrupador e entrega da v3

Funcionalidade BB-F-052 · requisito RF-BB-052 · versão documentada 2.0.1 · código 94155836a981e9912a59f2c826afcff7baa4f073.

Finalidade

Executar o modelo de trabalho B (ADR-0022): o épico agrupa tarefas que nascem da develop e fecham no merge; a release é cortada da develop e o que mudou o artefato sem homologação vai para produção com a feature flag desligada; a publicação promove os mesmos bytes da candidata.

Atores

Dono (decisões registradas: seleção, homologação, aprovação do ambiente de produção), IAs com posse confirmada, o controlador e os botões Start sprint, Create branches, Merge PR, Cut release, Candidate, Publish, Publish maintenance, QA reject e Cleanup.

Pré-condições

Projeto com workflow.model = grouping, quadro único, branch develop, decisão de flag do épico quando ele muda o artefato e o mecanismo de flags declarado pela stack; token do projeto com permissão de escrita.

Fluxo principal

bb sprint start cria teste, tarefas e documentação como sub-issues com dependências nativas e a branch de teste da develop; bb branches cria as desbloqueadas; bb merge mescla PR aprovado com o gate verde no SHA exato; bb release cut corta release/x.y.z com trava de versão e milestone; a candidata leva os épicos para QA; bb release publish confere o portão, mescla na main, promove a candidata, conclui os épicos entregues, fecha o milestone e devolve a main para a develop.

Validações

Merge nunca na main; aprovação nos dois idiomas; o portão da release lê flags.toml e os testes pendentes do conteúdo da própria release (lido como dado, sem seguir links para fora) e exige cada épico com o QA cumprido (estado Releasing, ou QA que as regras já deixam avançar: decisão do dono ou veredito de um agente independente) ou no escuro com todas as suas flags desligadas em produção; flag vencida bloqueia a release até ser renovada ou removida; testes de aceite pendentes só de épicos no escuro; nenhuma issue que bloqueie produção; candidata igual à ponta da release e ao head do PR da release, verde no SHA exato; manutenção só sem mudança de artefato. Os botões que mudam estado (Publish, QA reject, Publish maintenance) simulam por padrão, e nenhum valor digitado entra num script sem passar por variável de ambiente e validação.

Alternativas e erros

Reprovação na homologação — decisão registrada do dono (qa:rejected) ou, no QA delegado, veredito rejected de um agente independente para a candidata atual — cria uma tarefa de correção a partir da release e uma nova candidata; o botão sozinho nunca reprova; conflito ao devolver a main abre um PR de sync com conflict; um épico que perde a homologação entre o portão e a conclusão (decisão retirada) é relatado como pendente, nunca como no escuro; sem candidata publicada, o portão explica o motivo; promoção que falha não conclui nenhum épico; publicar de novo não duplica nada. No QA delegado (qa:agent, risco que o modo permite delegar), um agente sem posse no épico nem nas tarefas registra o veredito com bb qa verdict; com qa:human a homologação é sempre do dono.

Permissões

Publicação só depois da aprovação do ambiente production; correções e reprovações exigem a decisão registrada do dono (qa:rejected) ou, no QA delegado, o veredito rejected de um agente independente para a candidata atual; quem entrega nunca homologa (limite conhecido: com o token compartilhado de uma conta pessoal, o nome do agente em bb qa verdict é declarado por quem roda o comando; a separação forte exige uma conta-bot por agente); a faxina nunca apaga main, develop, releases, tags nem refs de trava (só relata posses vencidas há mais de uma semana) e só remove branches mescladas de issues fechadas sem PR aberto.

Resultados

Entregas com escopo controlado por flag, tarefas concluídas no merge, homologação sobre a candidata exata, produção com o artefato homologado e o repositório limpo depois de cada ciclo.

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.

flags.py

Implementação revisada.

Símbolo Linha
_field 16
parse 20
switch 58
_by_epic 80
release_problems 87
pending_problems 106

flows.py

Implementação revisada.

Símbolo Linha
_trusted 17
_sprint_option 21
_children_by_role 32
_legacy_view 41
start_sprint 45
_block 108
create_branches 115
_has 143
_owner_decided 147
merge_pr 159
current_version 198
release_items 203
cut_release 214
read_content 252
release_gate 262
child 73

delivery.py

Implementação revisada.

Símbolo Linha
_now 19
_trusted 23
_milestone 27
_epics 34
_has 38
candidate_ready 42
_flags 73
_green 82
_return_main 88
_latest_candidate 100
publish 109
publish_maintenance 190
correction_task 209
cleanup 240

Cenários e rastreabilidade

Requisitos · Matriz de rastreabilidade · Referência CLI

Fontes rastreadas