Hooks de Pré-commit e Checklists de Revisão

Q: Os hooks devem executar go test -race?

Geralmente não em cada commit - muito lento. Execute race na CI e opcionalmente no pré-push para alterações com muita concorrência.

Q: Como posso pular hooks legitimamente?

git commit --no-verify para emergências. Exija um post-mortem do incidente se usado em trabalho direcionado ao main.

Q: Os hooks funcionam com monorepos go.work?

Sim. Execute a partir da raiz do workspace; go test ./... respeita todos os módulos no arquivo de trabalho.

Q: Arquivos gerados devem ser formatados em hooks?

Formate na geração, não em cada hook de commit. Exclua *.pb.go de verificações em staging se a geração de código já formatar.

Q: Qual a relação com gopls format on save?

Salvar no editor reduz falhas de hook. Hooks ainda capturam contribuidores usando editores diferentes ou fluxos de trabalho apenas de CLI.

Q: O que pertence ao modelo de PR vs configuração do linter?

Automatize regras objetivas (formato, verificação de erro). Checklist cobre julgamento de design, operabilidade e segurança.

Q: Hooks podem chamar Docker?

Possível, mas lento. Prefira a toolchain go nativa no host para hooks de laptop.

Q: Como equipes remotas compartilham hooks?

Commite scripts/pre-commit.sh ou .pre-commit-config.yaml. Documente o passo de instalação; não comite .git/hooks diretamente.

Q: Os revisores devem re-executar make check?

Verifique pontualmente em PRs não triviais. Confie na CI para sinal autoritativo; verifique pontualmente ao tocar em tags de build ou go.mod.

Q: Com que frequência atualizar o checklist?

Trimestralmente ou quando retrospectivas de incidentes citarem temas de revisão perdidos. Itens menores e mais afiados superam listas longas e genéricas.

Hooks de pré-commit executam verificações rápidas de qualidade em cada commit.

Checklists de revisão de PR capturam o que a automação não pode ver: formato da API, modos de falha e operabilidade.

Juntos, eles encurtam os loops de feedback sem substituir a CI como autoridade de merge.

Receita

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

# scripts/pre-commit.sh
#!/usr/bin/env bash
set -euo pipefail
changed=$(git diff --cached --name-only --diff-filter=ACM | grep '\.go$' || true)
[ -z "$changed" ] && exit 0
echo "$changed" | xargs goimports -local example.com/mycorp -w
echo "$changed" | xargs gofmt -s -w
echo "$changed" | xargs go vet
go test ./...

chmod +x scripts/pre-commit.sh
ln -sf ../../scripts/pre-commit.sh .git/hooks/pre-commit

Quando usar isso:

Contribuidores enviam falhas de CI apenas de formatação repetidamente.
Onboarding de uma equipe onde make check ainda não é habitual.
Padronização de modelos de PR para serviços Go.
Divisão de verificações "devem passar localmente" vs "apenas CI" em documentação de plataforma.

Exemplo de Trabalho

.pre-commit-config.yaml (framework opcional):

repos:
  - repo: local
    hooks:
      - id: goimports
        name: goimports
        entry: goimports -local example.com/mycorp -w
        language: system
        types: [go]
      - id: go-test-quick
        name: go test
        entry: go test ./...
        language: system
        pass_filenames: false

Trecho do modelo de PR (.github/pull_request_template.md):

## Checklist de qualidade Go
- [ ] `make check` passa localmente
- [ ] Novo código tem testes para caminhos de erro
- [ ] Nenhum `context.Background()` em manipuladores de requisição
- [ ] Clientes HTTP/gRPC expiram e respeitam o cancelamento
- [ ] Migrações ou alterações de configuração documentadas no corpo do PR

Fluxo do contribuinte:

git add internal/api/handler.go
git commit -m "adiciona manipulador de saúde"
# pré-commit executa goimports, gofmt, go vet em arquivos .go em staging, depois go test ./...

O que isso demonstra:

Escopo dos hooks para arquivos .go em staging para velocidade.
Itens do checklist de PR visam julgamento de revisão que o vet não cobre.
make check permanece o portão completo documentado antes do push.

Mergulho Profundo

Como Funciona

Git invoca .git/hooks/pre-commit antes de criar um objeto de commit.
Saída não zero aborta o commit, mantendo o estado ruim local.
O framework pre-commit gerencia versões de hooks e compartilhamento via YAML commitado.
A CI ainda executa em checkouts limpos com versões de ferramentas fixadas.

Níveis de Hook

Nível	Verificações	Duração alvo
Pré-commit	goimports, gofmt, go vet em arquivos em staging	< 15s
Pré-push	`go test ./...`, golangci-lint	< 2m
CI	race, govulncheck, integração	minutos

Categorias de Checklist de Revisão de PR

Área	Perguntas do revisor
Erros	Envoltos com contexto? Erros sentinela documentados?
Concorrência	Propriedade de mutex/canal clara? Contexto cancelado na saída?
HTTP/gRPC	Timeouts, fechamento de corpo, códigos de status corretos?
Observabilidade	Logs estruturados com ID de requisição? Métricas para novos caminhos?
Segurança	Entrada validada? Segredos não registrados? SQL parametrizado?
Testes	Casos de teste de tabela para erros? Código propenso a race sob `-race` na CI?

Notas Go

.PHONY: check hook-install
hook-install:
	ln -sf ../../scripts/pre-commit.sh .git/hooks/pre-commit
 
check:
	golangci-lint run ./...
	go test -race ./...

Documente make hook-install no README após o clone.

Armadilhas

Executar golangci-lint em cada commit - Hooks lentos levam ao abuso de --no-verify. Correção: Mova lint pesado para pré-push ou apenas CI.
Hooks não instalados após o clone - Novos contratados silenciosamente pulam os hooks. Correção: make hook-install na documentação de onboarding ou use pre-commit install do pre-commit.
Diferente goimports -local do que na CI - Commit passa no hook, falha no pipeline. Correção: Fonte única de verdade em scripts/ compartilhada pelo hook e workflow.
Testar incorretamente apenas pacotes alterados - Perde quebras em dependentes. Correção: Pré-commit executa go test ./... ou go test $(go list ./...) no mínimo.
Itens de checklist nunca atualizados - Revisões de carimbo de borracha. Correção: Reduza para 5-8 itens de alto sinal; vincule a rubrica profunda a Padrões de Revisão de Código.
Formatação automática sem re-staging - Commit omite linhas formatadas. Correção: Re-adicione arquivos no hook ou use stages: [commit] do pre-commit com atualização de arquivo adequada.

Alternativas

Alternativa	Usar Quando	Não Usar Quando
Portões apenas de CI	Equipe pequena, sempre online	Monorepos sensíveis à latência
Pré-push em vez de pré-commit	Ruído de formatação incomoda durante commits WIP	Você precisa bloquear histórico não formatado
Bots de auto-correção de PR	Alto volume de contribuidores OSS	Trilhas de auditoria rigorosas no main
Reviewdog na CI	Exibir lint apenas na diff	Substituir completamente o feedback rápido local

FAQs

Os hooks devem executar go test -race?

Geralmente não em cada commit - muito lento.

Execute race na CI e opcionalmente no pré-push para alterações com muita concorrência.

Como posso pular hooks legitimamente?

git commit --no-verify para emergências.

Exija um post-mortem do incidente se usado em trabalho direcionado ao main.

Os hooks funcionam com monorepos go.work?

Sim.

Execute a partir da raiz do workspace; go test ./... respeita todos os módulos no arquivo de trabalho.

Arquivos gerados devem ser formatados em hooks?

Formate na geração, não em cada hook de commit.

Exclua *.pb.go de verificações em staging se a geração de código já formatar.

Qual a relação com gopls format on save?

Salvar no editor reduz falhas de hook.

Hooks ainda capturam contribuidores usando editores diferentes ou fluxos de trabalho apenas de CLI.

O que pertence ao modelo de PR vs configuração do linter?

Automatize regras objetivas (formato, verificação de erro).

Checklist cobre julgamento de design, operabilidade e segurança.

Hooks podem chamar Docker?

Possível, mas lento.

Prefira a toolchain go nativa no host para hooks de laptop.

Como equipes remotas compartilham hooks?

Commite scripts/pre-commit.sh ou .pre-commit-config.yaml.

Documente o passo de instalação; não comite .git/hooks diretamente.

Os revisores devem re-executar make check?

Verifique pontualmente em PRs não triviais.

Confie na CI para sinal autoritativo; verifique pontualmente ao tocar em tags de build ou go.mod.

Com que frequência atualizar o checklist?

Trimestralmente ou quando retrospectivas de incidentes citarem temas de revisão perdidos.

Itens menores e mais afiados superam listas longas e genéricas.

Relacionados

Noções Básicas de Qualidade de Código - script de hook mínimo
Aplicação de gofmt & goimports - flags de formato para hooks
Configuração do golangci-lint - o que adiar para a CI
Padrões de Revisão de Código para Equipes Go - rubrica do revisor
Portões de Qualidade da CI: Lint, Test, Race, Vuln - verificações de merge autoritativas

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

Checklists de revisão de PR capturam o que a automação não pode ver: formato da API, modos de falha e operabilidade.

Juntos, eles encurtam os loops de feedback sem substituir a CI como autoridade de merge.

Receita

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

# scripts/pre-commit.sh
#!/usr/bin/env bash
set -euo pipefail
changed=$(git diff --cached --name-only --diff-filter=ACM | grep '\.go$' || true)
[ -z "$changed" ] && exit 0
echo "$changed" | xargs goimports -local example.com/mycorp -w
echo "$changed" | xargs gofmt -s -w
echo "$changed" | xargs go vet
go test ./...

chmod +x scripts/pre-commit.sh
ln -sf ../../scripts/pre-commit.sh .git/hooks/pre-commit

Quando usar isso:

Contribuidores enviam falhas de CI apenas de formatação repetidamente.
Onboarding de uma equipe onde make check ainda não é habitual.
Padronização de modelos de PR para serviços Go.
Divisão de verificações "devem passar localmente" vs "apenas CI" em documentação de plataforma.

Exemplo de Trabalho

.pre-commit-config.yaml (framework opcional):

repos:
  - repo: local
    hooks:
      - id: goimports
        name: goimports
        entry: goimports -local example.com/mycorp -w
        language: system
        types: [go]
      - id: go-test-quick
        name: go test
        entry: go test ./...
        language: system
        pass_filenames: false

Trecho do modelo de PR (.github/pull_request_template.md):

## Checklist de qualidade Go
- [ ] `make check` passa localmente
- [ ] Novo código tem testes para caminhos de erro
- [ ] Nenhum `context.Background()` em manipuladores de requisição
- [ ] Clientes HTTP/gRPC expiram e respeitam o cancelamento
- [ ] Migrações ou alterações de configuração documentadas no corpo do PR

Fluxo do contribuinte:

git add internal/api/handler.go
git commit -m "adiciona manipulador de saúde"
# pré-commit executa goimports, gofmt, go vet em arquivos .go em staging, depois go test ./...

O que isso demonstra:

Escopo dos hooks para arquivos .go em staging para velocidade.
Itens do checklist de PR visam julgamento de revisão que o vet não cobre.
make check permanece o portão completo documentado antes do push.

Mergulho Profundo

Como Funciona

Git invoca .git/hooks/pre-commit antes de criar um objeto de commit.
Saída não zero aborta o commit, mantendo o estado ruim local.
O framework pre-commit gerencia versões de hooks e compartilhamento via YAML commitado.
A CI ainda executa em checkouts limpos com versões de ferramentas fixadas.

Níveis de Hook

Nível	Verificações	Duração alvo
Pré-commit	goimports, gofmt, go vet em arquivos em staging	< 15s
Pré-push	`go test ./...`, golangci-lint	< 2m
CI	race, govulncheck, integração	minutos

Categorias de Checklist de Revisão de PR

Área	Perguntas do revisor
Erros	Envoltos com contexto? Erros sentinela documentados?
Concorrência	Propriedade de mutex/canal clara? Contexto cancelado na saída?
HTTP/gRPC	Timeouts, fechamento de corpo, códigos de status corretos?
Observabilidade	Logs estruturados com ID de requisição? Métricas para novos caminhos?
Segurança	Entrada validada? Segredos não registrados? SQL parametrizado?
Testes	Casos de teste de tabela para erros? Código propenso a race sob `-race` na CI?

Notas Go

.PHONY: check hook-install
hook-install:
	ln -sf ../../scripts/pre-commit.sh .git/hooks/pre-commit
 
check:
	golangci-lint run ./...
	go test -race ./...

Documente make hook-install no README após o clone.

Armadilhas

Executar golangci-lint em cada commit - Hooks lentos levam ao abuso de --no-verify. Correção: Mova lint pesado para pré-push ou apenas CI.
Hooks não instalados após o clone - Novos contratados silenciosamente pulam os hooks. Correção: make hook-install na documentação de onboarding ou use pre-commit install do pre-commit.
Diferente goimports -local do que na CI - Commit passa no hook, falha no pipeline. Correção: Fonte única de verdade em scripts/ compartilhada pelo hook e workflow.
Testar incorretamente apenas pacotes alterados - Perde quebras em dependentes. Correção: Pré-commit executa go test ./... ou go test $(go list ./...) no mínimo.
Itens de checklist nunca atualizados - Revisões de carimbo de borracha. Correção: Reduza para 5-8 itens de alto sinal; vincule a rubrica profunda a Padrões de Revisão de Código.
Formatação automática sem re-staging - Commit omite linhas formatadas. Correção: Re-adicione arquivos no hook ou use stages: [commit] do pre-commit com atualização de arquivo adequada.

Alternativas

Alternativa	Usar Quando	Não Usar Quando
Portões apenas de CI	Equipe pequena, sempre online	Monorepos sensíveis à latência
Pré-push em vez de pré-commit	Ruído de formatação incomoda durante commits WIP	Você precisa bloquear histórico não formatado
Bots de auto-correção de PR	Alto volume de contribuidores OSS	Trilhas de auditoria rigorosas no main
Reviewdog na CI	Exibir lint apenas na diff	Substituir completamente o feedback rápido local

FAQs

Os hooks devem executar go test -race?

Geralmente não em cada commit - muito lento.

Execute race na CI e opcionalmente no pré-push para alterações com muita concorrência.

Como posso pular hooks legitimamente?

git commit --no-verify para emergências.

Exija um post-mortem do incidente se usado em trabalho direcionado ao main.

Os hooks funcionam com monorepos go.work?

Sim.

Execute a partir da raiz do workspace; go test ./... respeita todos os módulos no arquivo de trabalho.

Arquivos gerados devem ser formatados em hooks?

Formate na geração, não em cada hook de commit.

Exclua *.pb.go de verificações em staging se a geração de código já formatar.

Qual a relação com gopls format on save?

Salvar no editor reduz falhas de hook.

Hooks ainda capturam contribuidores usando editores diferentes ou fluxos de trabalho apenas de CLI.

O que pertence ao modelo de PR vs configuração do linter?

Automatize regras objetivas (formato, verificação de erro).

Checklist cobre julgamento de design, operabilidade e segurança.

Hooks podem chamar Docker?

Possível, mas lento.

Prefira a toolchain go nativa no host para hooks de laptop.

Como equipes remotas compartilham hooks?

Commite scripts/pre-commit.sh ou .pre-commit-config.yaml.

Documente o passo de instalação; não comite .git/hooks diretamente.

Os revisores devem re-executar make check?

Verifique pontualmente em PRs não triviais.

Confie na CI para sinal autoritativo; verifique pontualmente ao tocar em tags de build ou go.mod.

Com que frequência atualizar o checklist?

Trimestralmente ou quando retrospectivas de incidentes citarem temas de revisão perdidos.

Itens menores e mais afiados superam listas longas e genéricas.

Relacionados

Noções Básicas de Qualidade de Código - script de hook mínimo
Aplicação de gofmt & goimports - flags de formato para hooks
Configuração do golangci-lint - o que adiar para a CI
Padrões de Revisão de Código para Equipes Go - rubrica do revisor
Portões de Qualidade da CI: Lint, Test, Race, Vuln - verificações de merge autoritativas

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

Hooks de Pré-commit e Checklists de Revisão

Buscar na documentação

Hooks de Pré-commit e Checklists de Revisão