Contribuindo

Esta página reúne as convenções que uma mudança precisa seguir: em que idioma escrever, onde vivem as especificações, e como uma mudança se move por uma cadeia de cinco repositórios. A maioria dessas regras é imposta por um workflow em vez de confiada, e esta página diz quais.

Tudo aqui é escrito em inglês

Este repositório e todo repositório abaixo dele é escrito em inglês, sem exceção por tipo de artefato: comentários de código, mensagens de commit, títulos e corpos de pull request, issues e comentários de issue, .specs/, READMEs, documentação, ADRs, nomes de teste, mensagens de falha e changelogs.

Isso não é uma preferência de estilo. O repositório é público sob MIT OR Apache-2.0, tem remote próprio, pull requests próprios e leitores fora do time. Um comentário em outro idioma é uma barreira para quem chega.

A regra vale em toda profundidade da cadeia — crab/crab-shell-proxy, crab/crab-ganglion-harness, crab/crab-exoskeleton-webapp e crab/harness-sphere inclusos. O repositório privado de marketing que carrega este como submódulo escreve em português, e a fronteira é o diretório modules/ daquele repositório. Uma consequência que vale declarar: mover um documento através dessa fronteira significa traduzi-lo, não copiá-lo.

A regra governa artefatos, não conversa. Falar com o dono do projeto em outro idioma enquanto se escreve um comentário em inglês é correto, não inconsistente.

Onde vivem as especificações

O trabalho de especificação vive sob .specs/, nunca na raiz de um repositório. A convenção é a mesma em todo repositório que tem uma:

.specs/project/            PROJECT.md (vision), ROADMAP.md, STATE.md
.specs/features/<slug>/    spec.md, context.md, design.md, tasks.md, reports

Uma pasta por feature, nomeada com o slug da feature. Os artefatos de execução — notas de progresso, relatórios de tarefa, notas de implementação — vão na mesma pasta da feature a que pertencem. Não deixe arquivos de rascunho na raiz do repositório; se uma ferramenta colocar um lá, mova-o para a pasta da feature correspondente.

O .specs/features/ do repositório do produto é o maior deles e é onde o trabalho entre componentes é especificado. O crab-ganglion-harness não mantém um .specs/ próprio: a especificação dele vive no repositório do produto em .specs/features/crab-ganglion-harness/, e o README dele diz isso.

Uma especificação também é o lugar certo para uma decisão que de outro modo seria perdida. Vários dos comportamentos mais surpreendentes desta stack — por que a resposta chega inteira em vez de palavra por palavra, por que uma imagem de harness não carrega tag móvel — estão documentados como requisitos com um motivo declarado, e os comentários de código os citam por identificador.

A cadeia de submódulos

O zombie-crab-project carrega quatro submódulos, cada um um repositório separado com os seus próprios pull requests. Uma mudança que toca tanto um submódulo quanto o repositório do produto é portanto dois pull requests, ou três, ou cinco.

Um ponteiro só pode nomear um commit alcançável a partir do branch padrão daquele submódulo. Alcançável, não igual: apontar para um commit mais antigo em main é comum e permitido. Apontar para um commit que existe só em um branch de pull request não é — esse commit desaparece quando o branch desaparece, e este repositório fica descrevendo uma árvore que nada aponta.

Então a cadeia é mesclada de baixo para cima, um nível por vez. Mescle primeiro o pull request do submódulo, depois avance o ponteiro para o commit de merge:

git -C crab/<name> checkout main
git -C crab/<name> pull --ff-only
git add crab/<name>
git commit -m "chore(submodule): advance <name> to #<pr>"

Uma mudança pode ter dois filhos independentes travando um pai. O trabalho de harness-sphere-integration foi o primeiro: ele precisava de um pull request em harness-sphere e de um em crab-shell-proxy, nenhum bloqueando o outro, ambos mesclados antes de o pull request do pai poder passar. Irmãos não têm ordem entre si — só filhos e pais têm. Mescle-os na ordem em que a revisão terminar, depois avance os dois ponteiros.

Abrir o pull request do pai cedo é uma questão de julgamento, não uma violação. A checagem é o que segura, então “abra a cadeia inteira para eu revisar” é aceitável desde que o corpo do pull request diga quais ponteiros são cabeças de branch.

O que o CI impõe

As regras acima são impostas por workflows, porque a falha que elas evitam acontece no botão de merge e um arquivo de instruções não está lá. Uma cadeia de quatro pull requests foi uma vez mesclada de baixo para cima na mão e um deles entrou com um ponteiro numa cabeça de branch, o que exigiu um segundo pull request para corrigir. O arquivo de instruções que deveria evitar isso dizia a coisa certa e não foi lido por ninguém no momento que importava.

.github/workflows/submodule-pointers.yml roda em cada pull request que toca crab/** ou .gitmodules. Para cada submódulo ele lê o ponteiro na árvore, pergunta à API do GitHub qual é o branch padrão daquele repositório, e compara os dois. O pull request passa só quando a comparação diz identical — o ponteiro é a ponta do branch — ou behind, significando que o ponteiro é um ancestral da ponta, que é o caso comum de um atraso deliberado. Qualquer outra coisa falha, nomeando o ponteiro e dizendo para você mesclar o filho primeiro.

Dois detalhes valem saber. O workflow não clona nada; ele resolve tudo pela API, então um submódulo privado não precisaria de token próprio. E ele itera sobre .gitmodules, então cobre os quatro submódulos mesmo onde uma regra escrita ficou para trás e ainda fala em três. Se um arquivo de regra e um workflow um dia discordarem, o workflow é a verdade.

crab-exoskeleton-webapp/.github/workflows/mycelium-transport.yml quebra um pull request que adiciona uma chamada REST ao gateway mycelium fora da sua lista de permissões. A lista de permissões é a lista de exceções, com um motivo para cada entrada, e adicionar uma linha nela é um ato visível no pull request que precisa disso. Veja o capítulo do webapp.

Os Dockerfiles dos dois componentes em Go rodam go vet e a suíte de testes completa antes de linkar o binário, então um teste vermelho significa que nenhuma imagem é construída e nada é publicado. No crab-shell-proxy, que não tem workflow de pull request nenhum, esse build é o gate.

O que não é imposto importa tanto quanto. Nada roda a suíte de testes do webapp no CI, e nada roda cargo test ou cargo clippy para o harness-sphere. Rode isso localmente antes de pedir uma revisão; Trabalhando na stack lista os comandos exatos de cada repositório.

Uma mudança, de ponta a ponta

1. Escreva ou atualize a especificação sob .specs/features/<slug>/ no repositório a que a mudança pertence.
2. Faça a mudança no submódulo, com os seus testes, e rode as verificações daquele repositório localmente.
3. Abra o pull request do submódulo. O título, o corpo e os commits dele são em inglês.
4. Quando ele for mesclado, atualize o ponteiro no repositório do produto para o commit de merge e diga qual pull request ele nomeia.
5. Abra o pull request do repositório do produto. Se você o abriu antes para que a cadeia inteira pudesse ser revisada junto, diga no corpo quais ponteiros ainda são cabeças de branch.

Para onde ir agora

Trabalhando na stack tem os comandos de build e teste. Os capítulos de componente — crab-shell-proxy, crab-ganglion-harness, crab-exoskeleton-webapp e harness-sphere — descrevem o layout de código de cada repositório que você talvez esteja prestes a mudar.