Git & Github: Guia básico e boas práticas de Pull Request · mpoda

Entendendo Pull Request

De forma prática, o pull request é uma camada de segurança que podemos adicionar no repositório de nossos projetos, principalmente quando o repoistório é compartilhado com uma equipe.

Nessa camada é empacotado os commits, com os códigos novos ou alterados de uma determinada branch, acompanhada de uma descrição do que tem dentro do pacote, para que um outro desenvolvedor com maior experiência no projeto, ou até mesmo um arquiteto, realize uma análise, antes de realizar o merge entre branches.

Vamos a um exemplo:

Imagine que esteja trabalhando em uma aplicação que realiza serviços de cadastro de clientes. No momento está criado apenas a funcionalidade de cadastro cliente pessoa física (PF), mas o responsável pelo negócio do sistema, trás que vai ser preciso criar a funcionalidade para cadastro cliente pessoa jurídica (PJ).

Seguindo a ideia de boas práticas de desenvolvimento em repositórios, iremos estar criando uma branch a partir de desenvolvimento (desenv) com o nome "feature_cadastrar_cliente_pj", onde o desenvolvedor responsável irá começar a construir a solução.

Após alguns commits, ele finalizou a implementação do negócio e deseja agora subir para o ambiente de desenvolvimento, para disponibilizar a nova versão para testes, seja automáticos de e2e (end-two-end), ou para QA's da equipe testarem.

Porém, seguindo as práticas de segurança do repositório, ele precisa criar uma PullRequest, onde vai estar empacotado todos os commits, com seu código novo ou alterado, que ele realizou ao longo do processo de desenvolvimento, disponibilizando para o arquiteto do time analisar e verificar se está de acordo com as boas práticas da empresa.

Após o arquiteto realizar a code review e verificar que está tudo certo, ele irá aprovar o pull request, o que por fim irá fazer com que aconteça o merge entre as branches.

Diagrama mostrando o pull request na etapa de merge entre branch desenv e feature

Importância de utilizar Pull Request

Agora que entendemos o que é o Pull Request, vamos tentar compreender qual a importância dele:

Ele ajuda a manter a qualidade do código, uma vez que os revisores podem detectar e corrigir erros antes do merge.
Ajudar a documentar o histórico de desenvolvimento do projeto, fornecendo um registro de todas as alterações propostas e merges no repositório.

Tendo o significado e a importância do Pull Request, precisamos dar uma rápida olhada para as boas práticas e dicas para transformar essa camada de segurança ainda mais prática e funcional.

Imagem ilustrativa de desenvolvedor aguardando pull request

Boas práticas

Tamanho do pull request

É comum acontecer de acumular muitos commits em uma branch, e na hora de criar um pull request ter uma enorme quantidade de código para revisar.

Isso pode gerar um enorme problema a longo prazo, de acordo com um estudo realizado pela Cisco, pode ser um código com grande chances de impacto e também pode ocorrer falha humana, já que a revisão acabará não sendo tão prática, e o processo de code review pode se tornar preguiçoso e lento.

Então tome cuidado em não demorar muito para gerar um pull request! Não espere toda a funcionalidade ser desenvolvida, dependendo da complexidade, divida em pequenas partes e vá realizando a pull requests.

Título e descrição

Assim como ao escrever um código limpo, precisamos dar nomes que façam sentido, aqui também vale. Ao criar um pull request escreva bons títulos e descrições.

Aqui uma dica brilha, é possível criar templates para os pull request, usando eles toda vez que um desenvolvedor da equipe for fazer um pull request, já é adicionado um comentário padrão onde ele pode editar rapidamente apenas as partes relacionadas a alteração dele.

Logo a frente irei estar abordando algumas ideias de template e como colocar em seu projeto.

No caso de título, existem algumas opções, que você pode seguir:

Uma descrição bem resumida da funcionalidade (ou parte dela), adicionado recurso de consulta cliente por cpf;
Adicionar uma tag relacionada a ação realizada no código do pacote, exemplo: [Correção], [Funcionalidade], [Refatoração], [Lançamento], [Ajustes] e etc;
Caso trabalhe com aplicações de gerenciamento de tarefas, como Jira, Trello e etc, podemos colocar o id da tarefa/cartão, #777 [Funcionalidade] adicionado recurso de consulta cliente por cpf.

Templates de Pull Request

Podemos criar alguns templates para deixar padronizado os comentários que os desenvolvedores irão utilizar, dessa forma poderá aumentar a produtividade tanto da criação dos pull request, como também para facilitar a vida do responsável pela code review.

Exemplos de templates:

Para bugs:

## Como reproduzir o bug?
Descrever rapidamente como ocorre o bug e qual foi a solução criada.

## Checklist
- [ ] Eu adicionei|atualizei|corrigi os testes unitários do projeto (Se aplicável);
- [ ] Sem erros ou avisos no console após minha alteração;
- [ ] Tirei prints do antes e depois da correção do problema.[adicionar a screenshot]

Para novas funcionalidades

## Resumo
Escreva um breve resumo sobre o que foi alterado no sistema.
## Checklist
- [ ] Eu adicionei|atualizei|corrigi os testes unitários do projeto (Se aplicável);
- [ ] Sem erros ou avisos no console após minha alteração;
- [ ] Tirei prints do antes e depois da correção do problema.[adicionar a screenshot]

Customizado

Não é possível dar uma fórmula de bolo, já que cada padrão depende da empresa, tipo de projeto e etc, porém, podemos encontrar um exemplo mega completo de um template de Pull Request, no site Embedded Artistry, pode utilizar de exemplo e modificar para o seu caso.

Como adicionar em seu repositório

Tutorial para GitHub: https://docs.github.com/en/github/building-a-strong-community/creating-a-pull-request-template-for-your-repository
Tutorial para GitLab: https://docs.gitlab.com/ee/user/project/description_templates.html#creating-merge-request-templates
Tutorial para Azura DevOps: https://docs.microsoft.com/en-us/azure/devops/repos/git/pull-request-templates?view=azure-devops
Tutorial para Bitbucket: https://confluence.atlassian.com/bitbucketserver/create-a-pull-request-808488431.html

Conclusão

Espero que eu tenha alcançado o objetivo de te ensinar o que é Pull Request! Ao ler e testar esse tópico, você deve ser capaz de:

Explicar o que é Pull Request;
Qual a importância;
Boas práticas;
Como usar templates e para que servem.

Obrigado pelo seu tempo.
Compartilhem com seus colegas de estudo/trabalho.
Me acompanhem em minhas redes sociais:

Até a próxima!