Merge Requests

Como entregar código via Merge Request no GitLab.

O que é Merge Request (MR)?

Merge Request é a forma como código entra nas branches principais (develop e main).

Por que usar MR?

✅ Revisão obrigatória - Código passa por aprovação
✅ Validação automática - CI/CD roda antes do merge
✅ Histórico rastreável - Tudo documentado
✅ Discussão centralizada - Comentários no código
✅ Rollback seguro - Fácil reverter se necessário

REGRA ABSOLUTA

Ninguém faz merge direto em develop ou main, nem Maintainers.

Todo código entra via Merge Request. Exceção única: Lead Técnico em situações críticas

Fluxo Completo

1. Criar feature branch
2. Fazer commits (Conventional Commits)
3. Push da branch
4. Abrir MR no GitLab
5. [Opcional] Draft MR para feedback antecipado
6. Marcar como "Ready for Review"
7. Aguardar aprovação (1 obrigatória)
8. CI/CD passa automaticamente
9. Merge automático após aprovação
10. Branch deletada automaticamente

Criando um MR

1. Preparação Local

bash

# Certifique-se que está atualizado
git checkout develop
git pull origin develop

# Crie sua feature branch
git checkout -b feature/nome-da-funcionalidade

# Desenvolva com commits padronizados
git add .
git commit -m "feat(modulo): adiciona funcionalidade X"

# Push da branch
git push origin feature/nome-da-funcionalidade

2. Abrir MR no GitLab

No GitLab:

Acesse o repositório
Clique em "Create merge request" (aparece após o push)
Ou: Menu lateral → Merge Requests → New merge request

Configuração básica:

Source branch: sua feature branch
Target branch: develop (quase sempre)
Title: Título claro da mudança
Description: Use o template (preenchido automaticamente)

3. Preencher Template

O template do MR já vem com a estrutura. Preencha:

markdown

# Tarefa

[Link da issue/card]

## Tipo de Mudança

[x] Feature

## Breaking Changes

[ ] Esta MR contém breaking changes

## Contexto

Breve explicação do que foi feito e por quê

## O que foi feito

- Item 1
- Item 2

## Como validar

1. Passo 1
2. Passo 2

## Checklist (Definition of Done)

[x] Código revisado antes de solicitar aprovação
[x] Funcionalidade testada e funcionando
...

Template completo em .gitlab/merge_request_templates/default.md

Definition of Done

Todo MR deve atender à nossa Definition of Done.

Checklist mínima (FASE 1):

✅ Funcionalidade testada e funcionando
✅ Código revisado (auto-revisão)
✅ Conventional Commits seguidos
✅ Documentação atualizada (se aplicável)
✅ CI/CD passou sem erros
✅ 1 aprovação obtida

WARNING

O checklist completo e detalhado está na página da DoD.

Não duplique informações - sempre consulte a fonte oficial.

Draft MR (Work in Progress)

Use Draft MR quando quiser feedback antes de finalizar.

Quando usar Draft MR?

✅ Feature grande (>3 dias de trabalho)
✅ Mudança arquitetural (quer validar abordagem)
✅ Feedback antecipado (antes de refinar tudo)
✅ Mostrar progresso (time acompanha desenvolvimento)

Como usar?

Ao criar MR:

Marque checkbox "Mark as draft"
Ou adicione Draft: no título: Draft: feat(auth): adiciona login Google

Durante desenvolvimento:

MR fica visível para discussão
CI/CD roda normalmente
Time pode comentar e sugerir
Merge fica BLOQUEADO até marcar como Ready

Quando finalizar:

Clique em "Mark as ready"
Remove Draft: do título (se adicionou)
Aí entra no fluxo normal de aprovação

TIP

Draft MR não é obrigatório, mas é fortemente incentivado para features complexas.

Padrão de Branches

Siga a nomenclatura padrão para facilitar organização:

Tipo	Formato	Exemplo
Feature	`feature/descricao`	`feature/crud-equipamentos`
Fix	`fix/descricao`	`fix/validacao-cpf`
Docs	`docs/descricao`	`docs/atualiza-readme`
Refactor	`refactor/descricao`	`refactor/servico-notificacao`
Chore	`chore/descricao`	`chore/atualiza-dependencias`

Regras:

Sempre em minúsculas
Use hífen (não underscore)
Nome descritivo mas curto
Crie a partir da develop

bash

# ✅ Correto
git checkout -b feature/login-google
git checkout -b fix/timeout-api
git checkout -b docs/guia-deployment

# ❌ Errado
git checkout -b Feature/Login_Google  # maiúscula + underscore
git checkout -b minha-branch           # sem tipo
git checkout -b fix                    # sem descrição

TIP

Para entender a estratégia completa de branches, veja Estratégia de Branches.

Aprovações

Regras de Aprovação

Quantidade:

✅ 1 aprovação obrigatória (mínimo)

Quem pode aprovar:

✅ Maintainers
✅ Lead Técnico

Quem NÃO pode aprovar:

❌ Autor do MR (não pode aprovar o próprio)
❌ Developers (sem permissão de Maintainer)
Exceção: Lead Técnico pode aprovar MR em situações críticas

Processo de Aprovação

Para o autor:

Abrir MR preenchido completamente
Aguardar revisão
Responder comentários
Fazer ajustes se solicitado
Aguardar aprovação final

Para o revisor:

Verificar Definition of Done
Revisar código
Testar localmente (se necessário)
Comentar se houver problemas
Aprovar quando tudo estiver ok

TIP

Seja gentil nos comentários. Estamos construindo código em time!

Critérios de Bloqueio

MR NÃO PODE ser mergeado se:

❌ Bloqueios Automáticos (GitLab)

Pipeline quebrado - CI/CD precisa passar
0 aprovações - Precisa de 1 aprovação mínima
Conflitos - Branch precisa estar atualizada com base
Draft MR - Enquanto marcado como rascunho

⚠️ Bloqueios Manuais (Revisor)

"Como validar" vazio - Revisor precisa saber como testar
DoD não seguida - Sem justificativa válida
Conventional Commits violados - Mensagens fora do padrão
Documentação necessária faltando - Se mudança exige doc

PIPELINE QUEBRADO = BLOQUEIO ABSOLUTO

Se CI/CD falhou, MR não pode ser mergeado em hipótese alguma.

Corrija os erros antes de pedir aprovação.

Após Aprovação

Merge Automático

Quando aprovado + pipeline verde:

GitLab faz merge automaticamente
Branch é deletada automaticamente
Issue relacionada é fechada (se configurado)

Delete de Branch

Regra:

✅ Branches de feature/fix/docs são deletadas após merge
❌ Branches develop e main nunca são deletadas

Por quê deletar?

Mantém repositório limpo
Evita confusão com branches antigas
Histórico fica no Git de qualquer forma

WARNING

Se precisar da branch depois, pode recriá-la a partir do commit específico.

Boas Práticas

1. MR Pequenos

bash

# ✅ Bom: MR focado
feat(crud): adiciona CRUD de equipamentos
- 5 arquivos alterados
- ~300 linhas

# ❌ Ruim: MR gigante
feat: adiciona várias funcionalidades
- 50 arquivos alterados
- ~5000 linhas

Por quê MR pequenos?

Revisão mais rápida
Menos bugs passam
Conflitos mais fáceis de resolver
Rollback mais seguro

2. Descrição Clara

markdown

# ✅ Bom

## Contexto

Sistema precisa notificar usuários sobre vencimento de equipamentos.

## O que foi feito

- Criado cron diário
- Criado template de email
- Criado rota de teste manual

# ❌ Ruim

## Contexto

Fiz a notificação

## O que foi feito

- Código pronto

3. Commits Organizados

bash

# ✅ Bom: commits atômicos e claros
feat(notificacao): cria model de notificação
feat(notificacao): cria serviço de envio
feat(notificacao): adiciona cron diário
docs(notificacao): atualiza README

# ❌ Ruim: commit gigante
feat: adiciona notificação completa

4. Testes Antes de Pedir Review

bash

# Antes de abrir MR:
✅ Testei localmente?
✅ CI/CD vai passar?
✅ Revisei meu próprio código?
✅ Documentei o necessário?

Auto-revisão evita:

Console.log esquecido
Código comentado
Imports não usados
Variáveis não utilizadas

5. Responder Comentários

Quando revisor comentar:

✅ Responda cada comentário
✅ Marque como resolvido quando ajustar
✅ Explique se discordar (educadamente)
❌ Não ignore comentários

Casos Especiais

Hotfix em Produção

Para correções urgentes em produção:

bash

# 1. Branch direto da main
git checkout main
git pull origin main
git checkout -b hotfix/corrige-bug-critico

# 2. Commit e push
git commit -m "fix: corrige bug crítico de segurança"
git push origin hotfix/corrige-bug-critico

# 3. MR para main
# Target: main (não develop)

# 4. Após merge em main, fazer MR da main para develop
# Para sincronizar

DoD pode ser flexibilizada em hotfixes, mas:

❌ CI/CD quebrado - nunca flexibilizar
❌ Conventional Commits - sempre obrigatório
❌ Aprovação - sempre precisa

Após hotfix, criar issue para regularizar documentação.

Conflitos

Se aparecer conflito:

bash

# 1. Atualizar sua branch com a base
git checkout develop
git pull origin develop
git checkout sua-branch
git merge develop

# 2. Resolver conflitos localmente
# Editar arquivos, resolver <<<<<<< >>>>>>>

# 3. Commitar resolução
git add .
git commit -m "chore: resolve conflitos com develop"

# 4. Push
git push origin sua-branch

Rebase (Avançado)

Se quiser histórico linear:

bash

# Ao invés de merge, use rebase
git checkout sua-branch
git rebase develop

# Se houver conflitos, resolve e continua
git add .
git rebase --continue

# Force push (CUIDADO!)
git push origin sua-branch --force-with-lease

FORCE PUSH

Só use --force-with-lease se tiver certeza!

Nunca force push em develop ou main.

Template de MR

O template é configurado no GitLab e aparece automaticamente ao abrir um MR.

Localização no repositório:

.gitlab/merge_request_templates/default.md

Quando você abre um MR no GitLab, o conteúdo deste arquivo é carregado automaticamente no campo "Description".

TIP

Este template será criado como parte da implementação desta documentação.

Estrutura do Template

markdown

# Tarefa

[Link da issue/card]

## Tipo de Mudança

- [ ] Feature
- [ ] Fix
- [ ] Refactor
- [ ] Docs
- [ ] Chore

## Breaking Changes

- [ ] Esta MR contém breaking changes

## Contexto

<!-- Breve descrição do problema ou objetivo -->

## O que foi feito

-
-

## Como validar

1.
2.

## Checklist (Definition of Done)

- [ ] Código revisado antes de solicitar aprovação
- [ ] Funcionalidade testada e funcionando
- [ ] Conventional Commits seguidos
- [ ] Documentação atualizada (se aplicável)
- [ ] CI/CD passou sem erros

## Observações

<!-- Opcional: justificativas, decisões técnicas, etc -->

Validação Automática (CI/CD)

EM IMPLEMENTAÇÃO

Estas validações estão sendo implementadas gradualmente nos projetos.

Validações Planejadas

O CI/CD irá validar automaticamente:

Commits:

✅ Conventional Commits (commitlint)
✅ Mensagens com tamanho adequado

Código:

✅ Build passou sem erros
✅ Testes passaram (quando aplicável)

Template:

✅ Campo "Como validar" preenchido
✅ Campo "Contexto" preenchido (exceto MR tipo docs)

TIP

Quando estas validações forem implementadas, a documentação de CI/CD terá detalhes de como funcionam.

FAQ

Posso fazer merge local sem MR?

Não. Todo merge é via MR no GitLab, sem exceção.

E se for só um typo no README?

Mesmo assim, MR obrigatório. Processo é igual para todos os tamanhos de mudança.

Posso aprovar meu próprio MR?

Não. Autor não pode aprovar o próprio MR.

Quantas aprovações preciso?

1 aprovação obrigatória de Maintainer ou Lead Técnico.

E se o revisor demorar?

Mencione no Teams. Se urgente, fale com Lead Técnico.

Posso fazer force push?

Sim, na sua branch de feature (com --force-with-lease). Nunca em develop/main.

MR pode ter múltiplos commits?

Sim! O importante é cada commit seguir Conventional Commits.

Preciso fazer squash antes do merge?

Não é obrigatório. Mantenha commits organizados e está ok.

E se eu esquecer de deletar a branch?

GitLab deleta automaticamente após merge. Mas se esqueceu antes, delete manual.

Referências externas:

Dúvidas?

Consulte o Lead Técnico ou canal #dev.

Merge Requests ​

O que é Merge Request (MR)? ​

Por que usar MR? ​

Fluxo Completo ​

Criando um MR ​

1. Preparação Local ​

2. Abrir MR no GitLab ​

3. Preencher Template ​

Definition of Done ​

Draft MR (Work in Progress) ​

Quando usar Draft MR? ​

Como usar? ​

Padrão de Branches ​

Aprovações ​

Regras de Aprovação ​

Processo de Aprovação ​

Critérios de Bloqueio ​

❌ Bloqueios Automáticos (GitLab) ​

⚠️ Bloqueios Manuais (Revisor) ​

Após Aprovação ​

Merge Automático ​

Delete de Branch ​

Boas Práticas ​

1. MR Pequenos ​

2. Descrição Clara ​

3. Commits Organizados ​

4. Testes Antes de Pedir Review ​

5. Responder Comentários ​

Casos Especiais ​

Hotfix em Produção ​

Conflitos ​

Rebase (Avançado) ​

Template de MR ​

Estrutura do Template ​

Validação Automática (CI/CD) ​

Validações Planejadas ​

FAQ ​

Merge Requests

O que é Merge Request (MR)?

Por que usar MR?

Fluxo Completo

Criando um MR

1. Preparação Local

2. Abrir MR no GitLab

3. Preencher Template

Definition of Done

Draft MR (Work in Progress)

Quando usar Draft MR?

Como usar?

Padrão de Branches

Aprovações

Regras de Aprovação

Processo de Aprovação

Critérios de Bloqueio

❌ Bloqueios Automáticos (GitLab)

⚠️ Bloqueios Manuais (Revisor)

Após Aprovação

Merge Automático

Delete de Branch

Boas Práticas

1. MR Pequenos

2. Descrição Clara

3. Commits Organizados

4. Testes Antes de Pedir Review

5. Responder Comentários

Casos Especiais

Hotfix em Produção

Conflitos

Rebase (Avançado)

Template de MR

Estrutura do Template

Validação Automática (CI/CD)

Validações Planejadas

FAQ