Como uma tarefa se transforma em um pull request

Esta é a página de referência para o restante da documentação. Ela nomeia cada etapa de execução para que outros artigos possam ser precisos sobre onde algo ocorre.

O caminho#

your description
   │
   ▼
   specification   what will be built, and how you will know it worked
   │
   ▼
   plan            the ordered steps, reviewed before any code is written
   │
   ▼
   build           code and tests written in an isolated workspace
   │
   ▼
   verify          your test suite, plus checks and quality gates
   │
   ▼
   review          an automated review pass over the diff
   │
   ▼
   pull request    on a branch, in your repository, waiting for you

Especificação#

Coroid não começa com sua frase. Primeiro, ele transforma sua descrição em especificação: o que será construído, o que está explicitamente fora do escopo e os critérios de aceitação que determinam se o trabalho foi bem-sucedido.

Isso é importante porque os critérios de aceitação são o que a etapa de verificação utiliza como referência posteriormente. Uma especificação vaga gera resultados difíceis de avaliar.

Você pode ler e editar a especificação na aba Especificação antes do início da execução.

O guia de desenvolvimento orientado por especificação explica como escrever critérios testáveis, definir limites de escopo e manter a mesma definição de sucesso durante o planejamento, implementação e revisão.

Planejar#

Para qualquer coisa além de uma pequena alteração, a especificação se torna um plano: um conjunto ordenado de etapas, agrupadas em fases. Você aprova o plano antes que o código seja escrito.

Rejeitar um plano é barato e é a decisão correta quando a abordagem está errada. Rejeitar após o código ser escrito é caro. Esta é a etapa em que seu julgamento tem maior influência.

Construir#

Um agente clona o repositório em um espaço de trabalho isolado e trabalha ali. Ele lê o código, escreve a alteração e cria ou atualiza os testes.

O espaço de trabalho é descartável e específico por tarefa. Nada que um agente faça afeta sua branch padrão, e duas tarefas executadas simultaneamente não conseguem ver o trabalho em progresso uma da outra.

Verificar#

Sua própria suíte de testes é executada primeiro — esse é o sinal mais confiável disponível, pois codifica o que sua equipe já considera importante.

Além disso, portas de qualidade executam o que sua organização configurou: limites de cobertura, linting, varredura de segurança, testes de navegador em um ambiente de pré-visualização. Uma porta bloqueante interrompe a tarefa; uma porta consultiva registra um achado e permite que ela continue.

Revisão#

Um agente revisor lê o diff da mesma forma que um colega o faria e gera achados. Os achados que podem ser corrigidos são enviados de volta para retrabalho; os demais são anexados ao pull request para que você os veja.

É por isso que um Coroid pull request chega já revisado — não para substituir sua revisão, mas para que sua revisão não seja a primeira.

Pull request#

A branch é enviada e um pull request é aberto contra sua branch base, contendo a alteração, os testes, os resultados da verificação e os achados da revisão.

Coroid termina aqui. A fusão é sua responsabilidade.

Status das tarefas#

O status de uma tarefa indica onde ela se encontra no caminho descrito acima:

O que determina o throughput#

Um slot de agente executa uma tarefa por vez. Os slots definem quanto trabalho acontece em paralelo; eles não fazem com que uma única tarefa seja concluída mais rápido. A duração de uma tarefa depende do tamanho da alteração e do tempo que sua suíte de testes leva.

Próximo#

Funções dos agentes — qual agente cuida de qual etapa e o que cada um tem permissão para fazer.