Pull Request
PRs grandes geram um grande overhead no processo de review do código, facilitando a introdução de bugs.
Por este motivo, a otimização deste processo deve fazer parte do core de qualquer equipe ágil quando o assunto é desenvolvimento de software.
A velocidade de desenvolvimento do produto está diretamente relacionada à qualidade dos PRs submetidos ao repositório.
Porque você deve se preocupar com isso
Um bom pull request é revisado rápidamente;
Diminui a introdução de bugs na base de código;
Facilita o onboarding dos desenvolvedores que estão entrando no time.
Agiliza o processo de review e consequentemente o merge.
Com isso em mente, vamos detalhar os pontos que precisam de mais atenção ao criar um PR.
O tamanho do pull request
Procure criar pull requests pequenas, com foco, que atendam a um propósito único. Pull requests menores são mais fáceis e rápidas de revisar e mesclar, deixam menos espaço para bugs, além de fornecer um histórico mais claro das alterações.
O primeiro passo para identificar PRs problemáticos é observar a quantidade de linhas que ele altera na base de código.
Existem diversos estudos mostrando que quanto maior o PR, menores são as chances identificar bugs no code review.
Além disso, PRs grandes bloqueiam outros desenvolvedores que podem estar dependendo deste código.
Não seria eficiente definir um número máximo de linhas para um PR, porque cada equipe tem uma velocidade, mas o ideal é que o code review de um PR não leve mais do que 1h para ser feito.
Revise, crie e teste sua própria pull request antes de enviá-la. Isso permitirá que você detecte erros gerais e de digitação que você pode ter deixado passar, antes que outros comecem a revisar.
O princípio de responsabilidade única (SRP)
Outro ponto a se observar para criar um PR foda é seguir o conceito de SRP (Single responsibility principle)
The single responsibility principle is a computer programming principle that states that every module or class should have responsibility over a single part of the functionality provided by the software, and that responsibility should be entirely encapsulated by the class.
Assim como classes e modulos, PRs devem fazer apenas uma coisa.
Isso diminui drasticamente o overhead causado ao revisar um código que tenta resolver vários problemas.
Antes de submeter um PR para review, tente aplicar o principio de responsabilidade única. Caso este código esteja fazendo mais de uma coisa, quebre em outros Pull Requests.
Exemplos de PRs que tem apenas uma função:
Adicionar um atributo X no modelo Y
Adiciona o método create no controller X
Adiciona o componente Y no ReactJS
Migra os dados da coluna Y para a coluna X
Adiciona o plugin X
Atualiza a gem Y
Corrige o problema X na classe Y
O titulo e a descrição são importantes
Ao criar o titulo e a descrição do PR, considere que o reviewer está chegando hoje no seu time, e que este, não sabe o que se passa no resto do código.
É necessário que o PR explique o que efetivamente está sendo alterado.
Sempre que possível utilize imagens (screenshots) para demonstrar o que mudou — 2 screenshots com antes e depois são suficientes.
O titulo do PR deve ser autoexplicativo
O titulo deve ser suficiente para que qualquer dev consiga entender o que está sendo alterado.
Alguns exemplos:
Adiconar caso de teste para getEventTarget
Melhorar a mensagem de erro enigmática ao criar um componente começando com uma letra minúscula
Faça uma descrição útil
Escreva títulos e descrições claras para suas pull requests, para que os revisores consigam entender rapidamente o propósito da solicitação. Inclua o seguinte no corpo da pull request:
a finalidade
uma visão geral das alterações
links para algum contexto adicional, como problemas de acompanhamento ou conversas anteriores
Para ajudar os revisores, compartilhe o tipo de feedback necessário. Por exemplo, você precisa de uma olhada rápida ou de uma crítica mais profunda?
Se sua pull request consistir em alterações em vários arquivos, forneça orientação aos revisores sobre a ordem de revisão dos arquivos. Recomende por onde a revisão deve começar e como proceder.
Recapitulando
Tamanho do PR
Deve ser pequeno. O PR deve ter no máximo 500 linhas — somando as linhas adicionadas e removidas — ou deve ser pequeno o suficiente para revisado em até 1h.
PS: Se quiser aumentar ainda mais a qualidade dos pull requests e reduzir o tempo de revisão, faça um experimento realizando este número para 300 linhas.
Princípio de Responsabilidade Única
O pull request deve fazer apenas 1 coisa;
Título do PR
Faça um título autoexplicativo descrevendo o quê o PR faz.
Descrição do PR
Detalhamento com o quê foi alterado, porque foi alterado e como foi alterado. Caso necessário, adicione capturas de tela.
Last updated
