mr-description

Título e descrição do MR

"MR" abaixo significa a unidade de revisão em qualquer serviço que hospede o repositório: um merge request no GitLab, um pull request no GitHub, ou o equivalente em outro lugar, cloud ou auto-hospedado. Use o termo que o host usa ao escrever para o usuário. Para um MR pequeno (um único commit, por exemplo), escreva o texto e crie-o sem pedir confirmação. Para um maior, rascunhe o título e a descrição no chat para revisão primeiro. Crie-o ou atualize-o, com a CLI do host (glab, gh) ou API, apenas quando o usuário aprovar o texto e pedir.

Sempre atribua um novo MR ao usuário: --assignee @me com gh pr create, --assignee <username> com glab mr create.

PROJ-1234 abaixo representa qualquer ticket ao qual o MR pertence.

Título

• Uma linha imperativa que cubra todo o MR, não apenas seu maior commit.
• O título de um ticket é um ponto de partida, não a resposta. Amplie-o se o MR fizer mais do que o ticket diz.
• Não enquadre o título por uma alternativa rejeitada ("… em vez de sair"). Diga o que o MR faz.
• Anexe o ticket entre parênteses se houver um: … (PROJ-1234). Nunca invente um. Se as instruções do projeto ou workspace derem outro formato, como PROJ-1234 <descrição>, use esse.

Descrição

Estrutura:

1. Uma linha de abertura. Se houver um ticket, vincule-o com o verbo que se adequa ao seu tipo: "Resolve PROJ-1234." para um bug, "Fecha PROJ-1234." para uma tarefa ou história, "Parte de PROJ-1234." se o MR não a completar.
2. As mudanças:
   • Organizadas por commits. Leia o log de commits do branch primeiro. Apenas se ele tiver vários commits, cada um sendo um passo autocontido em vez de correções ou trabalho em andamento, diga na linha de abertura que o MR é melhor lido um commit de cada vez. Em seguida, forneça uma lista numerada com uma entrada por commit, em ordem, cada uma dizendo em uma a três frases o que o commit torna verdadeiro. Diga que cada commit passa nos testes por conta própria apenas se isso foi verificado ou o autor disser.
   • Caso contrário, incluindo um único commit: um parágrafo curto ou lista do que o MR torna verdadeiro, agrupado por tópico.
3. ## Mudanças de comportamento: o que um usuário da API pública vê de diferente. Deixe de fora mudanças internas e atributos privados. Omita a seção se não houver nenhuma.
4. ## Testes: apenas se algo sobre os testes precisar da atenção do revisor. Testes que passam, em hardware ou não, são assumidos e não declarados. Casos que precisam da seção, cada um com uma frase dizendo por quê:
   • um teste conhecido por falhar, ou pulado ou marcado como esperado para falhar;
   • um teste no MR que se desvia das convenções de teste do projeto;
   • uma mudança significativa na cobertura de testes, especialmente testes removidos.

Conteúdo:

• Não reafirme o que existia antes da mudança. Descreva o estado após ela. Uma remoção é a exceção, pois só pode ser nomeada contra o que existia.
• Não reafirme o ticket. O revisor pode lê-lo.
• Sem contexto de sessão: sem "conforme discutido", sem histórico de revisão, sem relato de como o trabalho ocorreu.
• Sem instruções para executar testes ou jobs de CI. A descrição é para o revisor, e o autor executa os testes.
• Sem rodapé "Gerado com" e sem atribuição de ferramenta, mesmo quando o harness pedir uma. Esta regra tem precedência.
• Mantenha conciso. Remova uma entrada ou uma cláusula que um revisor não sentiria falta.

Verificação do texto

• Verifique cada afirmação em relação ao código no commit que ela descreve, não de memória ou rascunhos anteriores. Preste atenção particular a afirmações sobre o comportamento antigo e a afirmações sobre comportamento que um commit posterior altera.
• Pesquise (grep) cada identificador que o texto nomeia. Uma classe ou método que não existe mais, ou que ainda não existe naquele commit, é um erro comum.
• Baseie qualquer coisa em ## Testes no que realmente foi executado ou no que o diff mostra. Não afirme uma execução que não ocorreu.
• Aplique todo skill instalado que cubra a limpeza de prosa gerada ao título e à descrição. Onde tal skill conflitar com as instruções do projeto (CLAUDE.md ou equivalente), as instruções do projeto vencem.