Draft PRs e WIP: sinalizando trabalho em progresso

1. Introdução ao Conceito de Work in Progress no Git

No desenvolvimento de software moderno, a transparência sobre o estado do trabalho é essencial para equipes colaborativas. Work in Progress (WIP) refere-se a código que está sendo desenvolvido, mas ainda não está pronto para ser integrado ao branch principal. Sinalizar WIP corretamente evita confusões, merges acidentais e retrabalho.

Tradicionalmente, desenvolvedores mantinham branches locais para trabalho em andamento, sem compartilhá-los com a equipe. Essa abordagem, porém, limitava a colaboração precoce e impedia que colegas acompanhassem o progresso ou oferecessem feedback antes da conclusão. Com a popularização de plataformas como GitHub, GitLab e Bitbucket, surgiram os Draft Pull Requests (PRs) como uma forma de sinalizar intenção e status sem expor código incompleto a merges acidentais.

Os Draft PRs funcionam como um "aviso" visual: o trabalho ainda está em andamento, mas o desenvolvedor optou por compartilhá-lo para discussão, revisão ou validação contínua.

2. Draft Pull Requests: O Que São e Como Funcionam

Um Draft PR é um pull request que não pode ser mergeado até que seja explicitamente marcado como "pronto para revisão". Suas principais características incluem:

  • Impedimento de merge: o botão de merge fica desabilitado na interface.
  • CI restrito: algumas pipelines podem ser configuradas para não executar em drafts.
  • Indicador visual: badges como "Draft" ou "WIP" aparecem no título.

Criação via Interface

No GitHub, ao abrir um novo pull request, há um dropdown que permite selecionar "Create draft pull request". No GitLab, o equivalente é o prefixo "Draft:" no título. No Bitbucket, usa-se a opção "Open pull request as draft".

Criação via Linha de Comando

Com a CLI do GitHub (gh), é possível criar um draft PR diretamente:

gh pr create --draft --title "[WIP] Refatora módulo de autenticação" --body "Trabalho em andamento. Feedback sobre a estrutura é bem-vindo."

Ou, de forma mais manual, após fazer push de um branch:

git push origin minha-branch
gh pr create --draft

Para GitLab via CLI (glab):

glab mr create --draft --title "WIP: Adiciona endpoint de relatórios"

3. Quando e Por Que Usar Draft PRs

Draft PRs são úteis em diversos cenários:

Colaboração Precoce

Um desenvolvedor pode abrir um draft PR para solicitar feedback sobre a arquitetura antes de implementar todos os detalhes. Por exemplo:

# Branch: wip/refatora-api
# Draft PR title: [WIP] Refatora camada de API para usar padrão Repository

Proteção contra Merges Acidentais

Em equipes com políticas de branch protection, um draft PR impede que código incompleto seja integrado acidentalmente ao branch principal. Isso é especialmente importante em projetos com deploys automáticos.

Cenários Comuns

  • Refatoração: quando se está reestruturando código existente e quer validação incremental.
  • Experimentos: para testar uma abordagem alternativa e discutir com o time.
  • Revisão de design: antes de escrever todos os testes ou documentação.

4. Estratégias de Nomenclatura e Convenções para WIP

Adotar convenções claras ajuda a equipe a identificar rapidamente o estado de cada branch ou PR.

Prefixos em Branches

wip/nova-funcionalidade
draft/correcao-bug-critico
feature/wip-integracao-pagamento

Marcadores em Commits

No título ou corpo da mensagem de commit:

[WIP] Adiciona validação de CPF
WIP: endpoints da API de usuários

Labels ou Tags em PRs

Plataformas como GitHub permitem criar labels customizadas:

  • status: wip
  • status: draft
  • feedback-needed

Exemplo de configuração em um template de PR:

## Status
- [ ] WIP - Trabalho em andamento
- [ ] Pronto para revisão

5. Transição de Draft para PR Completo

Quando o trabalho atinge um estado de prontidão, é necessário converter o draft em um PR normal.

Critérios de Prontidão

  • Código compila sem erros.
  • Testes unitários e de integração passam.
  • Documentação mínima foi atualizada.
  • Revisão de código inicial foi considerada.

Processo de Conversão

No GitHub, basta clicar em "Ready for review" no draft PR. Pela CLI:

gh pr ready <número-do-pr>

Paralelamente, é recomendado:

  1. Remover prefixos [WIP] do título.
  2. Atualizar a descrição com informações finais.
  3. Solicitar revisores explicitamente.

Atualização Automática com CI

Muitas equipes configuram pipelines para rodar apenas quando o PR não é draft. Por exemplo, no GitHub Actions:

jobs:
  test:
    if: github.event.pull_request.draft == false
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm test

6. Integração com Ferramentas de CI e Automação

Draft PRs podem ser integrados a pipelines para evitar execuções desnecessárias e proteger branches.

Bloqueio de Merges

No GitHub, regras de branch protection podem exigir que PRs não sejam draft para permitir merge. Exemplo de configuração via API:

curl -X PUT \
  -H "Authorization: token SEU_TOKEN" \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/usuario/repo/branches/main/protection \
  -d '{
    "required_pull_request_reviews": {"required_approving_review_count": 1},
    "required_status_checks": {"strict": true, "contexts": ["continuous-integration"]},
    "enforce_admins": true
  }'

Pipelines Condicionais

Evitar deploys em drafts é uma prática comum. Exemplo com GitLab CI:

deploy:
  script: deploy.sh
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event" && $CI_MERGE_REQUEST_DRAFT == "true"'
      when: never
    - when: always

Exemplo Prático: GitHub Actions

Workflow que executa apenas em PRs não-draft:

name: CI
on:
  pull_request:
    types: [opened, synchronize, ready_for_review]
jobs:
  build:
    if: github.event.pull_request.draft == false
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: make build

7. Boas Práticas e Armadilhas Comuns

Evitar Draft PRs Longos Demais

Draft PRs que permanecem abertos por semanas perdem o propósito. Prefira iterações curtas e frequentes: abra drafts para feedback rápido e converta para PR completo assim que possível.

Comunicação Clara

Utilize o template do PR para comunicar o estado do trabalho:

### Status
Este PR está em draft. Ainda faltam:
- [ ] Implementar validação de entrada
- [ ] Adicionar testes de integração
- [ ] Revisar nomenclatura de métodos

Cuidado com Notificações Excessivas

Draft PRs geram notificações para revisores mesmo que o trabalho não esteja pronto. Considere usar labels como do-not-merge ou configurar o repositório para não notificar revisores em drafts. No GitHub, é possível marcar revisores apenas quando o PR sair do draft.

Armadilha: Esquecer de Converter

É comum que um draft PR fique pronto, mas o desenvolvedor esqueça de removê-lo do estado draft. Para evitar isso, configure lembretes automáticos ou revise periodicamente a lista de PRs abertos.

Referências