Desenvolvimento

15 ago, 2017

Mastering on GitHub #1 – Pull Requests

Publicidade

Bem-vindos ao primeiro artigo da série Mastering on GitHub! O intuito dessa série é compartilhar as melhores práticas (e recolher feedbacks) sobre como melhorar o fluxo de trabalho do seu time utilizando o GitHub e afins.

Não deixe de ler as dicas no final do texto!

Pull Requests

Abrir um Pull Request é algo corriqueiro para alguns, mas um verdadeiro pesadelo para outros. Como algumas outras práticas dentro do mundo do desenvolvimento, o ato de abrir um Pull Request se tornou tão mecânico e “obrigatório”, que perdemos um pouco a habilidade de dissertar sobre a sua função ou até mesmo importância.

Por quê?

Como tudo na vida, o senso comum prevalece. É muito difícil você conseguir justificar o motivo de uma decisão que cria burocracia, diminui a velocidade com que você entrega código e foge das suas responsabilidades de escritor de código.

Bom, sabemos que um Pull Request é um conjunto de modificações que você precisa incorporar no seu projeto, mas precisa de uma certa aprovação ou validação de outras pessoas do seu time e empresa antes que sua solução seja incorporada.

Essa aprovação é muito importante porque você está criando um contrato e o resto do time assina como testemunha de que aquele pedaço de código supre um requisito do sistema. Essa prática é muito importante para criar a responsabilidade partilhada entre todos, eliminando aquela ideia de que uma determinada pessoa introduziu um possível bug.

Considero o ato de abrir um Pull Request como um quality assurance dos desenvolvedores. A aprovação ou não daquele código é uma forma de se previnir de futuras dores de cabeça.

Manter o histórico das modificações

Andando sempre de mão dada com commits curtos e de boa descrição, seu repositório é um grande livro e os Pull Requests servem como marcadores, nota de página e observações necessárias para que o leitor possa compreender por completo aquele monte de texto.

Devemos, então, encarar um Pull Request como um manifesto declarativo de suas intenções e do que seu código irá tocar, alterar, incluir ou prevenir.

Em um ambiente que exige uma resposta rápida e certeira, um Pull Request de qualidade é uma forma de você dar contexto a sua modificação, a fim de mantê-la rastreável e descentralizar o conhecimento.

Uma vez que qualquer pessoa pode ler e entender (independente de linguagem ou framework), o corpo do seu pedido é uma maneira muito forte de passar segurança e confiança no que você está incluindo (ou excluindo).

O que esperar de um Pull Request de qualidade?

Título

  • Como eu posso pesquisar esse Pull Request quando necessário?

Um título de qualidade é quando você ou qualquer pessoa possa utilizar as ferramentas de busca do GitHub para encontrar com facilidade o que está procurando.

Por consequência, você irá precisar quebrar a cabeça pra resumir e passar em poucas palavras o que você está modificando.

Uma vez que a sua modificação nem sempre reflete a sua tarefa ou história (levando em consideração que sua empresa adotou uma ferramenta de gerenciamento de projeto, por exemplo, o Jira), não se prenda ao título que seu product manager escreveu.

Título geralmente replicado do ticket
Título explicativo, detalhando melhor o que o cenário

O GitHub é uma ferramenta para todos, mas principalmente para os desenvolvedores. Não tenha medo de colocar em seu título termos mais práticos e técnicos.

Descrição

  • Qual problema eu estou resolvendo?
  • Como eu resolvi esse problema?
  • Por que eu decidi seguir com o caminho X, sendo que o Y também é possível?
  • O que é importante ressaltar?

Pense na sua descrição como um artigo técnico: você precisa convencer seus leitores, com argumentos e evidências que seu tema é importante e válido.

Aqui, você precisa ser o mais claro e pragmático possível para não receber um tl;dr.

Deixe claro o que você está resolvendo e como você está o fazendo. Cole trecho de código, os links que você utilizou para montar sua solução (Stack Overflow) e até documentação se for necessário.

É uma boa prática você utilizar uma estratégia de markdown para melhorar a leitura e como uma forma de indexação mental do que você está sugerindo.

Tunnando sua descrição

Bibliotecas incluídas

  • Por que adotar essa biblioteca?

Dependendo do seu ambiente, inclusão de bibliotecas significam aumentar o tempo de build e tamanho do arquivo compilado final. Sabemos que incluir uma biblioteca tem seus riscos, como se prender a uma solução ou depender da manutenção de seus mantenedores.

É muito importante que você documente em seu Pull Request o motivo da inclusão e deixe claro que você realizou uma pesquisa necessária antes de tomar essa decisão.

O importante aqui é que você deixe claro o problema que você enfrentou e como a biblioteca resolve (e bem) o seu caso.

Como testar?

Só você tem em mente tudo o que você enfrentou e os comportamentos que modificou. É de suma importância que você detalhe como testar o que você está propondo, indicando todos os possíveis problemas que aquela modificação pode acarretar.

Se você incluiu testes, é o espaço para você incluir seu arquivo de teste e o que você cobriu com ele.

Além de tudo isso, você explica como testar seu código é de muita valia para um time de Q.A. que irá complementar com seu próprio script de teste. Seu Pull Request irá servir como uma referência de uso muito poderosa para outras áreas.

Inclua tudo o que você julga necessário para garantir o comportamento desejado daquela modificação.

Vale ressaltar que essa parte da descrição não retira a necessidade de ter documentado em alguma outra plataforma (como o Jira ou Confluence). O how to test dentro do Pull Request tem mais uma ideia do que pode ter quebrado com minha modificação do que como validar a minha modificação.

Seja claro no que você quer de feedback

Levando em consideração de que alguma(s) pessoas irão avaliar seu código, é muito importante que você inclua em sua descrição qual tipo de feedback você precisa.

Aqui, você irá descrever caso queira levantar uma discussão ou até mesmo se precisa de algum complemento.

Também, é super válido você pedir para que opinem sobre o design do seu código.

Inclua os colaboradores do seu Pull Request

Inclua as pessoas envolvidas (seja desenvolvedor ou não) em sua tarefa. Explore com quem você conversou e validou. Isso irá enriquecer (e muito) o seu argumento e decisão.

Caso você tenha feito pair programming com alguém, utilize a biblioteca hitch para incluir quem lhe auxiliou no desenvolvimento.

Inclua imagens e vídeos

Uma imagem vale mais que mil palavras. Nada melhor para descrever seu pull request do que uma imagem descritiva do seu sistema que resume bem o que você quer dizer.

Inclua um Check List

Em algumas situações, temos alguns passos necessários para que seu código funcione, ou até para que um bug seja reproduzido.

O conceito de check list é incrível, pois irá documentar e facilitar para que outras pessoas consigam reproduzir e criar o ambiente necessário para que seu pedaço de código funcione.

Também, um Check List é interessante para adicionar em seu template. Se há steps que seu time acordou, aqui é o melhor lugar para inclui-los.

Pontos de atenção

É de suma importância que você evidencie todos os pontos de atenção necessários que seu código pode afetar.

Também, caso seu pull request depende de algum outro, aqui é o melhor lugar para você mostrá-lo.

Dicas e boas práticas

  • Mantenha seu Pull Request pequeno: quanto maior e mais complexo seu Pull Request, mais perigoso é sua inclusão. Validar pequenas partes de código é muito mais seguro, fácil e vantajoso. Defina um número máximo de inserções e exclusões de linhas com seu time.
  • Pratique a quebra de tarefas e Pull Requests: como consequência do item anterior, exercite com seu time como vocês podem diminuir e evoluir suas tarefas para que sejam granulares o bastante para garantir Pull Request pequenos e concisos.
  • Cuidado com sua linguagem: uma vez que qualquer pessoa de sua organização pode ler, é de suma importância que você tome bastante cuidado com a forma que você se expressa. A forma com que você escreve irá impactar a maneira com o que irão avaliar e te sugerir melhorias.
  • Não tenha medo de perder tempo escrevendo: sabemos que não estamos 8 horas por dia codando, então não tenha medo de gastar um tempo praticando melhores Pull Requests.
  • Não seja hipócrita: não exija um Pull Request de qualidade caso você não o faça. É muito importante que os Pull Request sejam algo evolutivo, e cabe a cada um contribuir para criar o melhor template para seu time.
  • Crie templates: uma vez que o GitHub permite a criação de templates, defina com seu time o que melhor se encaixa e atende para seu universo.
  • Seja chato(a): recuse Pull Requests que não se encaixem nos requisitos pré-definidos com o time.
  • Gaste seu inglês: uma vez que a maioria dos repositórios no GitHub é em inglês, essa é uma ótima forma de você treinar para estar craque para poder participar de projetos open source espalhados por aí.

Conclusão

Como tudo no universo da engenharia, uma boa prática leva tempo: tanto para ser adotada, quanto para colher seus frutos.

Um Pull Request de qualidade significa uma mudança de mindset que irá acontecer naturalmente em seu time. Comece com pequenas e efetivas iniciativas que façam sentido no seu dia a dia.

Esse foi o primeiro post da saga Mastering on GitHub! Sua opinião é muito importante, então não deixe de deixar suas impressões e dicas!