O que esta base pede de quem chega

Mentoria é específica a uma base de código antes de ser qualquer outra coisa, então comece por esta. O que alguém que chega precisa saber antes de escrever uma linha que seria mesclada?

Os números

$ git log --all --oneline | wc -l
3858
$ git log --all --oneline --author=dependabot | wc -l
24

Um autor humano (com três grafias do mesmo nome) e 3.834 commits; os outros 24 são do Dependabot. É essa a situação sobre a qual é esta aula. Não um time grande com um programa de integração, mas o caso bem mais comum em que as convenções são reais, consistentes e inteiramente na cabeça de uma pessoa até alguém as escrever.

Alguém escreveu. O MEMORY.md tem 659 linhas e abre:

Este arquivo é a referência autoritativa para todo padrão, convenção e decisão arquitetural desta base. Leia antes de tocar em qualquer código.

Esse documento é o artefato de mentoria mais valioso deste repositório. E a aula 5 é sobre o que ele faz bem e onde ele deu errado em silêncio.

O que não é derivável do código

A dificuldade de integração não se mede em arquivos. Ela se mede em decisões que quem chega não consegue derivar lendo. E esta base tem muitas porque é opinativa de formas que são corretas e não óbvias.

Cinco que quem chega quebraria no primeiro dia:

Nomeação por domínio, sem exceções.

"Todo pedaço de código pertence a um domínio nomeado. Não há exceções: não adicione controllers, models, serviços ou helpers no nível raiz."

Quem chega roda rails g controller Profiles, recebe app/controllers/profiles_controller.rb, e quebrou uma regra que nada no código impõe.

Erros de unicidade dizem "is not available". Nunca "has already been taken". A razão é enumeração de usuários: a mensagem padrão diz a um atacante que um e-mail está cadastrado. Nada na validação explica isso, e "consertar" de volta para o padrão do Rails parece uma limpeza.

Consultas devolvem objetos Data, nunca objetos Pagy.

"Consultas precisam ser agnósticas de infraestrutura. Recebem page e per_page, usam .limit/.offset, e devolvem registros + total_count."

Devolver um Pagy é o que o README da gem mostra, e está errado aqui.

O form_with sempre recebe um url: explícito. A inferência por array de model quebra com models em namespace, e a falha é um erro de rota confuso e não um claro.

Identificadores do Stimulus usam o prefixo ui-- casando com o diretório. Um controller em controllers/ui/navbar_controller.js é ui--navbar, e quem o nomeia navbar recebe silêncio e não um erro.

flowchart TB
  C["ler o código"] --> A["o que ele faz"]
  C --> B["quais são as convenções"]
  B -.->|"não derivável"| D["sem controllers no nível raiz"]
  B -.->|"não derivável"| E["'is not available' previne enumeração"]
  B -.->|"não derivável"| F["consultas devolvem Data, nunca Pagy"]
  B -.->|"não derivável"| G["form_with precisa de url: explícito"]
  B -.->|"não derivável"| H["prefixo ui-- nos identificadores do Stimulus"]

O padrão nas cinco

Olhe o que essas cinco têm em comum. Cada uma tem uma razão, a razão não é visível no lugar da regra, e seguir a convenção geral do Rails produz o resultado errado.

Essa combinação é o que torna uma base difícil de entrar, e não é um defeito. Cada uma daquelas decisões é defensável, e três delas protegem algo específico. O custo é que quem chega não consegue chegar a nenhuma delas sendo competente, e vai produzir um pull request errado de formas que parecem descuido.

Essa é a coisa mais importante de entender antes de mentorar alguém. O primeiro pull request da pessoa vai violar convenções que ela não tinha como conhecer, e como você responde a isso decide a maior parte do que vem depois.

O que isso significa para uma primeira tarefa

Uma boa primeira tarefa neste repositório é uma em que o domínio já está escolhido, o padrão já existe ao lado. E as convenções estão visíveis no arquivo vizinho. Acrescentar um objeto de consulta ao lado de outros cinquenta e oito. Acrescentar um spec a um arquivo que já tem seis.

Uma primeira tarefa ruim é uma que cruza domínios, cria um namespace novo, ou não tem exemplo local, porque a única fonte de convenções de quem chega é um documento de 659 linhas que a pessoa ainda não leu. E ninguém lê 659 linhas antes do primeiro commit.

Pontos-chave

• 3.834 commits de um autor humano: as convenções são consistentes, reais, e estiveram numa cabeça até serem escritas.
• O MEMORY.md tem 659 linhas e se declara a referência autoritativa.
• A dificuldade de integração se mede em decisões que quem chega não consegue derivar lendo o código.
• Cinco aqui têm uma razão invisível no lugar da regra, onde a convenção geral do Rails dá a resposta errada.
• Uma boa primeira tarefa tem o domínio escolhido e um exemplo funcionando no arquivo vizinho.