Revisão de Código com PRs do GitHub

Q: Revisores devem executar o código localmente?

Para mudanças arriscadas, sim: gh pr checkout então go test ./.... CI verde é necessário, mas nem sempre suficiente.

Q: Quais labels ajudam repositórios Go?

breaking, module-deps, needs-changelog, security. Filtra notas de lançamento e prioridade de revisão.

Pull requests (PRs) são o portão de integração para repositórios de módulos Go.

Uma revisão eficaz mantém as alterações pequenas, aponta o impacto do go.mod e verifica os testes – não apenas opiniões de estilo.

Resumo

Um bom PR Go declara a mudança de comportamento, o impacto no módulo/API e como os testes foram executados.

Revisores analisam deltas de API exportada, tratamento de erros, concorrência e diffs de dependência antes de aprovar.

PRs grandes atrasam o trunk; divida por pacote ou feature flag quando possível.

Receita

Cartão de receita de referência rápida – pronto para copiar e colar.

Título do PR: internal/parse: rejeitar entrada vazia em Decode

Modelo de corpo do PR:

## Resumo
- Rejeita entrada vazia em `Decode` com `ErrEmptyInput`
 
## Impacto no módulo
- Sem novas dependências
- A variável de erro exportada é uma adição compatível
 
## Plano de testes
- [ ] go test ./...
- [ ] go vet ./...
- [ ] go mod tidy (sem diff)
 
## Capturas de tela / logs
N/A

Quando usar isso:

Estabelecer normas de revisão de equipe para um novo serviço ou biblioteca Go.
Treinar revisores para identificar mudanças de módulo que quebram compatibilidade.
Reduzir a latência de revisão em monorepos com diffs ruidosos.
Onboarding de contribuidores que conhecem apenas revisão em nível de linguagem.

Exemplo de Trabalho

Um contribuidor abre um PR adicionando verificações de saúde gRPC:

// internal/health/grpc.go (excerto)
package health
 
import "google.golang.org/grpc/health/grpc_health_v1"
 
func Register(s *grpc.Server) {
    srv := grpc_health_v1.NewHealthServer()
    grpc_health_v1.RegisterHealthServer(s, srv)
}

# excerto do go.mod
+ google.golang.org/grpc v1.68.0

Checklist do revisor:

Confirmar que go test ./... está verde na CI.
Perguntar se a saúde deve ser opcional via configuração.
Verificar se a versão do gRPC está alinhada com a configuração existente do servidor.
Verificar se o caminho de importação não vaza internal/ além do limite do módulo.
Solicitar nota no changelog se o comportamento público voltado para o operador mudou.

Aprovação após o autor documentar a flag de opt-out e a verificação de tidy passar.

O que isso demonstra:

Seções de API e dependências na descrição guiam o foco da revisão.
Revisores tratam o diff do go.mod como primeira classe, não como ruído.
Perguntas sobre comportamento precedem discussões triviais sobre nomenclatura.

Mergulho Profundo

Como Funciona

O autor envia o branch e abre um PR contra main.
A CI executa testes, vet, tidy, lint.
Revisores deixam comentários em linhas, pacotes ou arquivos de módulo.
O autor envia correções; o GitHub reexecuta as verificações.
O mantenedor faz o merge quando as aprovações e as verificações exigidas satisfazem a proteção do branch.

A fila de merge do GitHub (opcional) serializa os merges para manter o trunk verde sob carga.

Orientação sobre Tamanho de PR

Tamanho	Linhas (aprox.)	Resultado da Revisão
Pequeno	menos de 200	Merge no mesmo dia provável
Médio	200-400	Necessita de tempo de revisão focado
Grande	400+	Dividir, a menos que seja renomeação mecânica

Alterações mecânicas (go fix, atualização de protobuf gerado) podem exceder os limites se isoladas e rotuladas.

Pontos de Revisão Conscientes de Módulo

Área	Pergunta
Símbolos exportados	Isso promete compatibilidade para consumidores do módulo?
`go.mod`	Novo peso transitivo? Versão justificada?
`internal/`	Alguma importação interna ilegal entre módulos?
Erros	Empacotados com `%w`? Erros sentinela vs dinâmicos documentados?
Concorrência	Ciclo de vida da goroutine, cancelamento de contexto, data races?
Testes	Baseados em tabela? Cobrem caminhos de erro? Vale a pena usar `-race`?

Campos de Descrição que Ajudam

Comportamento visível ao usuário - Flags de CLI, códigos HTTP, chaves de configuração.
Alterações que quebram compatibilidade - Requer caminho /v2 ou bump principal?
Rollout - Feature flag, etapas de migração.
Benchmarks - Se um caminho crítico foi alterado, cole o resumo do benchstat.

Etiqueta do Revisor

Solicite alterações para correção, segurança do módulo ou testes ausentes.

Comentários de "nitpicks" devem ser opcionais (prefixo nit:).

Aprove quando os problemas forem menores e confie em issues de acompanhamento do autor para débitos técnicos.

Armadilhas

Aprovação automática de CI verde - Testes podem não cobrir pacotes sem casos de teste. Correção: examine o diff em busca de funções exportadas não testadas.
Ignorar go.sum em massa - Pode ocultar uma troca na cadeia de suprimentos. Correção: leia go mod why -m para novos módulos.
Revisão apenas de estilo em caminhos críticos - Perde regressões de alocação. Correção: peça nota de benchmark ou profiling.
Diff gerado gigante - Oculta edições manuais. Correção: PRs separados para regeneração vs lógica.
Revisar PRs de fork sem checkout do mantenedor - Difícil de executar localmente. Correção: use gh pr checkout ou confie na matriz de CI.

Alternativas

Alternativa	Usar Quando	Não Usar Quando
Programação em par	Picos de design complexos	Equipe distribuída assíncrona
PRs empilhados	Alterações sequenciais dependentes	Revisores sem ferramentas de stack
Solicitação automática via CODEOWNERS	Propriedade de monorepo grande	Biblioteca pequena de duas pessoas
Merge do mantenedor sem PR	Hotfix de emergência	Fluxo normal de recursos

FAQs

Quão pequeno deve ser um PR Go?

Mire em uma única mudança lógica que os revisores possam manter na memória de trabalho.

Separe refatorações de mudanças de comportamento entre PRs.

Revisores devem executar o código localmente?

Para mudanças arriscadas, sim: gh pr checkout <n> então go test ./....

CI verde é necessário, mas nem sempre suficiente.

Como revisar PRs apenas de dependências?

Verifique o changelog e os avisos de segurança para módulos atualizados.

Execute testes e inspecione go mod why para caminhos inesperados.

Quais labels ajudam repositórios Go?

breaking, module-deps, needs-changelog, security.

Filtra notas de lançamento e prioridade de revisão.

Renomeações de API devem ir em um PR?

Prefira um PR de renomeação mecânica separado das mudanças de comportamento.

Revisão mais fácil e bisect mais limpo.

Como lidar com PRs WIP (Work In Progress)?

Use PRs draft.

Converta para pronto apenas quando a descrição, testes e tidy estiverem completos.

Comentários em arquivos gerados importam?

Comente nas entradas do gerador ou nos alvos do Makefile, não diretamente nas linhas de *.pb.go.

Regenere em um commit de acompanhamento.

Como revisar mudanças de cancelamento de contexto?

Rastreie os caminhos de chamada de manipuladores HTTP/gRPC para o trabalho em segundo plano.

Faltas de verificações de ctx.Done() são bloqueadores de lançamento.

Bibliotecas devem exigir entradas de changelog?

Sim para API exportada ou comportamento em que os consumidores dependem.

Aplicativos podem usar notas de lançamento apenas no momento da tag.

Quão rápido a primeira revisão deve acontecer?

Dentro de um dia útil mantém o fluxo do trunk saudável.

Defina SLA da equipe e alterne o dever de revisão.

E sobre auto-merge?

Ok quando as verificações exigidas são fortes e os limites de tamanho de PR são aplicados.

Evite para bumps de dependência sem uma olhada humana.

Como revisar PRs entre módulos em um monorepo?

Liste todos os go.mod tocados.

Confirme se diretivas de workspace ou replace não foram acidentalmente commitadas.

Relacionados

Estratégias de Branching & Fluxo Baseado em Trunk - Branches curtos tornam a revisão tratável
GitHub Actions para Repos Go - CI em que os revisores confiam
Git para Equipes Go - Por que PRs mesclados se tornam releases de módulos
Tags Assinadas & Releases de Módulos Go - Disciplina de tagging pós-merge
Melhores Práticas de Git & GitHub - Hábitos portáteis de revisão e Git

Versões da Stack: Esta página foi escrita para Go 1.26.x (padrão Green Tea GC, modernizadores go fix - verifique o patch na compilação), chi (latest - verifique na compilação), gin (latest - verifique na compilação), echo (latest - verifique na compilação), google.golang.org/grpc (latest - verifique na compilação), sigs.k8s.io/controller-runtime (latest - verifique na compilação), kubebuilder (latest - verifique na compilação), tinygo (latest - verifique os alvos de placa na compilação), wazero (latest - verifique na compilação) e golangci-lint (latest - verifique o conjunto de linters na compilação).

Uma revisão eficaz mantém as alterações pequenas, aponta o impacto do go.mod e verifica os testes – não apenas opiniões de estilo.

Resumo

Um bom PR Go declara a mudança de comportamento, o impacto no módulo/API e como os testes foram executados.

Revisores analisam deltas de API exportada, tratamento de erros, concorrência e diffs de dependência antes de aprovar.

PRs grandes atrasam o trunk; divida por pacote ou feature flag quando possível.

Receita

Cartão de receita de referência rápida – pronto para copiar e colar.

Título do PR: internal/parse: rejeitar entrada vazia em Decode

Modelo de corpo do PR:

## Resumo
- Rejeita entrada vazia em `Decode` com `ErrEmptyInput`
 
## Impacto no módulo
- Sem novas dependências
- A variável de erro exportada é uma adição compatível
 
## Plano de testes
- [ ] go test ./...
- [ ] go vet ./...
- [ ] go mod tidy (sem diff)
 
## Capturas de tela / logs
N/A

Quando usar isso:

Estabelecer normas de revisão de equipe para um novo serviço ou biblioteca Go.
Treinar revisores para identificar mudanças de módulo que quebram compatibilidade.
Reduzir a latência de revisão em monorepos com diffs ruidosos.
Onboarding de contribuidores que conhecem apenas revisão em nível de linguagem.

Exemplo de Trabalho

Um contribuidor abre um PR adicionando verificações de saúde gRPC:

// internal/health/grpc.go (excerto)
package health
 
import "google.golang.org/grpc/health/grpc_health_v1"
 
func Register(s *grpc.Server) {
    srv := grpc_health_v1.NewHealthServer()
    grpc_health_v1.RegisterHealthServer(s, srv)
}

# excerto do go.mod
+ google.golang.org/grpc v1.68.0

Checklist do revisor:

Confirmar que go test ./... está verde na CI.
Perguntar se a saúde deve ser opcional via configuração.
Verificar se a versão do gRPC está alinhada com a configuração existente do servidor.
Verificar se o caminho de importação não vaza internal/ além do limite do módulo.
Solicitar nota no changelog se o comportamento público voltado para o operador mudou.

Aprovação após o autor documentar a flag de opt-out e a verificação de tidy passar.

O que isso demonstra:

Seções de API e dependências na descrição guiam o foco da revisão.
Revisores tratam o diff do go.mod como primeira classe, não como ruído.
Perguntas sobre comportamento precedem discussões triviais sobre nomenclatura.

Mergulho Profundo

Como Funciona

O autor envia o branch e abre um PR contra main.
A CI executa testes, vet, tidy, lint.
Revisores deixam comentários em linhas, pacotes ou arquivos de módulo.
O autor envia correções; o GitHub reexecuta as verificações.
O mantenedor faz o merge quando as aprovações e as verificações exigidas satisfazem a proteção do branch.

A fila de merge do GitHub (opcional) serializa os merges para manter o trunk verde sob carga.

Orientação sobre Tamanho de PR

Tamanho	Linhas (aprox.)	Resultado da Revisão
Pequeno	menos de 200	Merge no mesmo dia provável
Médio	200-400	Necessita de tempo de revisão focado
Grande	400+	Dividir, a menos que seja renomeação mecânica

Alterações mecânicas (go fix, atualização de protobuf gerado) podem exceder os limites se isoladas e rotuladas.

Pontos de Revisão Conscientes de Módulo

Área	Pergunta
Símbolos exportados	Isso promete compatibilidade para consumidores do módulo?
`go.mod`	Novo peso transitivo? Versão justificada?
`internal/`	Alguma importação interna ilegal entre módulos?
Erros	Empacotados com `%w`? Erros sentinela vs dinâmicos documentados?
Concorrência	Ciclo de vida da goroutine, cancelamento de contexto, data races?
Testes	Baseados em tabela? Cobrem caminhos de erro? Vale a pena usar `-race`?

Campos de Descrição que Ajudam

Comportamento visível ao usuário - Flags de CLI, códigos HTTP, chaves de configuração.
Alterações que quebram compatibilidade - Requer caminho /v2 ou bump principal?
Rollout - Feature flag, etapas de migração.
Benchmarks - Se um caminho crítico foi alterado, cole o resumo do benchstat.

Etiqueta do Revisor

Solicite alterações para correção, segurança do módulo ou testes ausentes.

Comentários de "nitpicks" devem ser opcionais (prefixo nit:).

Aprove quando os problemas forem menores e confie em issues de acompanhamento do autor para débitos técnicos.

Armadilhas

Aprovação automática de CI verde - Testes podem não cobrir pacotes sem casos de teste. Correção: examine o diff em busca de funções exportadas não testadas.
Ignorar go.sum em massa - Pode ocultar uma troca na cadeia de suprimentos. Correção: leia go mod why -m para novos módulos.
Revisão apenas de estilo em caminhos críticos - Perde regressões de alocação. Correção: peça nota de benchmark ou profiling.
Diff gerado gigante - Oculta edições manuais. Correção: PRs separados para regeneração vs lógica.
Revisar PRs de fork sem checkout do mantenedor - Difícil de executar localmente. Correção: use gh pr checkout ou confie na matriz de CI.

Alternativas

Alternativa	Usar Quando	Não Usar Quando
Programação em par	Picos de design complexos	Equipe distribuída assíncrona
PRs empilhados	Alterações sequenciais dependentes	Revisores sem ferramentas de stack
Solicitação automática via CODEOWNERS	Propriedade de monorepo grande	Biblioteca pequena de duas pessoas
Merge do mantenedor sem PR	Hotfix de emergência	Fluxo normal de recursos

FAQs

Quão pequeno deve ser um PR Go?

Mire em uma única mudança lógica que os revisores possam manter na memória de trabalho.

Separe refatorações de mudanças de comportamento entre PRs.

Revisores devem executar o código localmente?

Para mudanças arriscadas, sim: gh pr checkout <n> então go test ./....

CI verde é necessário, mas nem sempre suficiente.

Como revisar PRs apenas de dependências?

Verifique o changelog e os avisos de segurança para módulos atualizados.

Execute testes e inspecione go mod why para caminhos inesperados.

Quais labels ajudam repositórios Go?

breaking, module-deps, needs-changelog, security.

Filtra notas de lançamento e prioridade de revisão.

Renomeações de API devem ir em um PR?

Prefira um PR de renomeação mecânica separado das mudanças de comportamento.

Revisão mais fácil e bisect mais limpo.

Como lidar com PRs WIP (Work In Progress)?

Use PRs draft.

Converta para pronto apenas quando a descrição, testes e tidy estiverem completos.

Comentários em arquivos gerados importam?

Comente nas entradas do gerador ou nos alvos do Makefile, não diretamente nas linhas de *.pb.go.

Regenere em um commit de acompanhamento.

Como revisar mudanças de cancelamento de contexto?

Rastreie os caminhos de chamada de manipuladores HTTP/gRPC para o trabalho em segundo plano.

Faltas de verificações de ctx.Done() são bloqueadores de lançamento.

Bibliotecas devem exigir entradas de changelog?

Sim para API exportada ou comportamento em que os consumidores dependem.

Aplicativos podem usar notas de lançamento apenas no momento da tag.

Quão rápido a primeira revisão deve acontecer?

Dentro de um dia útil mantém o fluxo do trunk saudável.

Defina SLA da equipe e alterne o dever de revisão.

E sobre auto-merge?

Ok quando as verificações exigidas são fortes e os limites de tamanho de PR são aplicados.

Evite para bumps de dependência sem uma olhada humana.

Como revisar PRs entre módulos em um monorepo?

Liste todos os go.mod tocados.

Confirme se diretivas de workspace ou replace não foram acidentalmente commitadas.

Relacionados

Estratégias de Branching & Fluxo Baseado em Trunk - Branches curtos tornam a revisão tratável
GitHub Actions para Repos Go - CI em que os revisores confiam
Git para Equipes Go - Por que PRs mesclados se tornam releases de módulos
Tags Assinadas & Releases de Módulos Go - Disciplina de tagging pós-merge
Melhores Práticas de Git & GitHub - Hábitos portáteis de revisão e Git

Versões da Stack: Esta página foi escrita para Go 1.26.x (padrão Green Tea GC, modernizadores go fix - verifique o patch na compilação), chi (latest - verifique na compilação), gin (latest - verifique na compilação), echo (latest - verifique na compilação), google.golang.org/grpc (latest - verifique na compilação), sigs.k8s.io/controller-runtime (latest - verifique na compilação), kubebuilder (latest - verifique na compilação), tinygo (latest - verifique os alvos de placa na compilação), wazero (latest - verifique na compilação) e golangci-lint (latest - verifique o conjunto de linters na compilação).

Revisão de Código com PRs do GitHub

Buscar na documentação

Revisão de Código com PRs do GitHub