Escrevendo Boas PRs e READMEs

Por que a Escrita Tecnica e Importante

Em code review, a descricao do seu PR e o ponto de entrada do revisor. Uma boa descricao de PR pode:

• Permitir que o revisor entenda rapidamente o que voce fez
• Reduzir perguntas de ida e volta
• Mostrar que voce pensou bem
• Economizar seu tempo quando voce consultar o historico daqui a 3 meses

Da mesma forma, um bom README pode:

• Permitir que novos membros comecem rapidamente
• Reduzir perguntas repetitivas
• Fazer o projeto parecer profissional

Dica

Escrita tecnica nao e escrita criativa. Tem formulas, tem padroes — aprenda-os e voce escrevera muito bem.

Estrutura Padrao de Descricao de PR: What/Why/How/Testing

1. What (O que foi feito)

Resumo conciso, uma frase.

Refactor authentication flow to support OAuth2 and magic link sign-up

Expressoes-chave:

• Add X — Nova funcionalidade
• Fix X — Correcao de bug
• Refactor X — Reescrever codigo (sem mudar funcionalidade)
• Optimize X — Melhorar desempenho
• Implement X — Implementar um design

2. Why (Por que foi feito)

A parte mais frequentemente ignorada. Explique contexto e motivacao.

Why:
- Users requested passwordless sign-up option
- Current session-based auth doesn't scale to multiple domains
- OAuth2 is industry standard for enterprise integrations

Sinais de um bom Why:

• Menciona razao de negocio (necessidade do usuario, desempenho, manutenibilidade)
• Explica por que a solucao atual nao e suficiente
• Explica por que esta solucao e melhor

Cuidado

“Because I wanted to” nao e um bom Why. Diga a razao real.

3. How (Como foi feito)

Visao geral de alto nivel da implementacao tecnica.

How:
1. Created JWT service using Web Crypto API for signing/verification
2. Replaced SessionMiddleware with AuthMiddleware that validates JWT
3. Added OAuth2 routes for Google/GitHub sign-in
4. Migrated user session storage from cookie to JWT claims
5. Added magic link generation and validation

Breaking changes:
- Moved user auth state from server session to JWT (stateless)
- Clients now need to store and send JWT in Authorization header

4. Testing (Como foi testado)

Explique como voce verificou que a mudanca esta correta.

Testing:
- Manual testing: Verified OAuth2 sign-in with Google and GitHub accounts
- Verified JWT expiration and refresh flow works correctly
- Existing auth tests pass (147 tests)
- Added 23 new tests for JWT and OAuth2 flows
- Load tested with 1000 concurrent requests (no issues)
- Tested on staging environment with real data

Nota

A secao “Testing” e muito importante — diz ao revisor que voce ja testou, e ele nao precisa gastar tempo procurando bugs.

Armadilhas Gramaticais da Escrita Tecnica

1. Tempos verbais (erro mais comum)

Principio: Presente para o que o codigo faz, passado para as mudancas que voce fez

Erro	Razao	Correto
”The function was created to handle X”	Parece narrativa historica	”The function handles X” ou “This PR adds a function that handles X"
"The code will validate input”	Muito incerto	”The code validates input"
"We added the feature” (no README)	README nao conta historia	”This feature allows users to…“

2. Artigos (erro comum de falantes de portugues)

Principio: Primeira mencao usa “a/an”, subsequentes usam “the”; ou use plural para evitar artigos

Erro	Razao	Correto
”We refactored authentication flow”	Nao esta claro qual flow	”We refactored the authentication flow"
"Function handles case when user logs in”	Falta “the"	"The function handles the case when a user logs in”

3. Voz passiva excessiva

Principio: Ingles prefere voz ativa. A menos que voce nao queira dizer quem fez, use ativa

Passiva (interferencia comum)	Ativa (melhor)
“The JWT is generated by the server"	"The server generates the JWT"
"The user data is stored in D1"	"We store user data in D1"
"Breaking changes were introduced"	"This PR introduces breaking changes”

4. Diferencas sutis entre sinonimos

Palavra	Uso
Add	Nova funcionalidade (nao existia): “Add OAuth2 support”
Implement	Implementar um design conhecido: “Implement the design from #123”
Create	Gerar um novo objeto: “Create JWT service”
Build	Construir sistema: “Build the CI/CD pipeline”
Refactor	Melhorar codigo existente sem mudar funcionalidade: “Refactor auth middleware”
Optimize	Melhorar desempenho: “Optimize query performance”
Fix	Corrigir bug: “Fix race condition in cache”

Checklist Rapido para Descricao de PR

Antes de enviar o PR, verifique:

• Secao What explica claramente a mudanca
• Secao Why tem razao de negocio ou tecnica (nao apenas “quis fazer assim”)
• Secao How descreve o design de alto nivel, revisor nao precisa ler codigo linha por linha
• Secao Testing descreve a cobertura de testes
• Sem voz passiva excessiva
• Artigos usados corretamente (“the” vs “a”)
• Tempos verbais consistentes (presente para funcionalidade do codigo, passado para mudancas)
• Links para issues relacionadas (se houver)

Checklist Rapido para README

• Primeira frase explica claramente o que o projeto e
• Tem demo ou screenshot
• Passos de instalacao claros e reproduziveis
• Exemplos de uso podem ser copiados diretamente
• Tem guia de contribuicao (se aceitar contribuicoes externas)
• Tem licenca
• Linguagem concisa (nem muito academica nem muito casual)