Se você já contribuiu em um projeto, seja em um aplicativo seu, no trabalho ou em alguma ferramenta de código aberto, provavelmente já criou uma solicitação de pull (geralmente chamada de PR, ou Pull Request). Ela é uma solicitação para que um código seu seja incorporado ao código principal.

Usamos pull requests para garantir que apenas códigos de qualidade sejam incorporados na branch (versão do código) principal. Às vezes, porém, perdemos algumas coisinhas depois de uma sessão cansativa de codificação, desenvolvendo um novo recurso.

Na pior das hipóteses, esses erros passam desapercebidos pela equipe e são incorporados na base de código principal, criando bugs ou ineficiências no código. Na melhor das hipóteses, encontrar esses pequenos erros pode custar o tempo de outros membros da equipe de percebê-los e mostrá-los.

Como sou particularmente suscetível a abrir um pull request lazy (preguiçoso), então fiz o que qualquer desenvolvedor faria... encontrei uma maneira de automatizar a checklist de PRs e me forçar a fazer o trabalho!

Este tutorial mostra como criar uma extensão no navegador que gerará automaticamente essa checklist para os PRs e ocultará o botão Create Pull Request (Criar Pull Request) até que você verifique todos os itens da lista.

Pegue suas ferramentas

Antes de começar, precisamos juntar algumas coisas.

Faça uma lista do que você quer verificar no seu código

Por um momento, esqueça qualquer ferramenta ou automação... pense sobre o que deve fazer um bom pull request e liste esses itens.

O que facilita a revisão de outros PRs? Qual é um erro comum sobre o qual as pessoas costumam comentar a respeito?

Se você precisar de algumas ideias, aqui está o que eu incorporei na minha própria lista.

• Tudo deve estar ordenado alfabeticamente
• Instruções sobre como os revisores podem testar o código localmente
• Adicionados os testes do código
• Captura de tela do recurso/correção do bug (se aplicável)
• Se algum novo texto for adicionado, ele precisa ser internacionalizado
• Qualquer novo elemento adicionado precisa ter seu rótulo (aria label)
• Nenhum console.logs involuntário deixado para trás após a etapa de debugging
• Uso de nomes claros e concisos para variáveis ​​e funções
• Explicação de todas as soluções possíveis do código e por que foi feita aquela escolha
• Adição de comentários para tornar as novas funções mais claras
• Etiquetas de PR foram adicionadas
• Atualizei qualquer arquivo do histórico/changelog

Se você ainda não tiver certeza, converse com desenvolvedores mais experientes da sua equipe e veja o que eles estão procurando quando analisam PRs.

Crie uma conta no PixieBrix (ferramenta de automação do navegador)

Existem várias extensões de navegador que permitem criar automações, mas achei o PixieBrix extremamente poderoso, a comunidade é bem amigável e ajuda bastante.

O PixieBrix oferece a plataforma low-code mais versátil para estender as aplicações web que você e suas equipes já usam. O resultado? Você obtém a experiência produtiva e personalizada que precisa... e merece. (Fonte: site do PixieBrix)

Para criar a automação que ensino abaixo, você precisará se inscrever para uma conta gratuita do PixieBrix.

Basta selecionar "Start for Free" (Começar gratuitamente) e seguir os passos para criar uma conta. Será pedido também que você instale a extensão PixieBrix do Chrome.

Feito isso, estamos prontos para começar!

Como construir a automação da checklist de um PR

Se você quiser seguir um caminho mais curto, e só ativar a extensão que eu já criei e editar como quiser.

Mas se quiser criá-lo do zero e se familiarizar com o funcionamento de uma automação de navegador, siga estas etapas.

Passo 1 – abra o editor de páginas no PixieBrix

Para construir extensões no PixieBrix, você não precisa do VSCode ou de qualquer outro editor. Você pode fazer tudo no seu navegador mesmo.

Eu gosto de começar indo para a página em que quero que a ação aconteça – neste caso, github.com.

Para acessar o editor, clique com o botão direito do mouse em qualquer página da web para abrir o menu de contexto e selecione Inspect (Inspecionar) para abrir as Ferramentas do desenvolvedor. Procure nas guias (você sabe, aquelas que dizem coisas como Elements, Console, Network etc) até ver a do PixieBrix e selecione-a.

Você também pode ser solicitado a conceder algumas permissões. Fora isso, você encontrará uma página em branco com um botão no canto superior esquerdo que diz "Add" (Adicionar). É por aí que vamos começar.

Passo 2 – adicionar um bloco de acionamento

Para construir uma extensão no PixieBrix, você precisa encadear blocos de acionamento. Você pode pensar nesses blocos como funções e em uma extensão como sendo a função principal que executa as funções menores na sequência que você configurar.

Você tem várias opções para acionar esta extensão.

Você pode escolher uma ação manual, como adicionar um botão a uma página, um menu de contexto (que é quando você clica com o botão direito do mouse em uma página da web – o mesmo menu a partir do qual você chegou ao Inspect) ou um atalho no teclado.

O painel da barra lateral abre um painel no lado direito do seu navegador, mas isso não é realmente um acionador. Ele é usado para criar uma exibição para outro acionador.

Para o nosso fluxo de trabalho, especificamente, usaremos a opção Trigger, que executa a extensão sempre que você carregar uma página da web específica e os critérios adicionais configurados forem atendidos.

Esta será a aparência inicial:

Você pode alterar o nome na parte superior para o nome que quiser, como, por exemplo, Github PR Checklist.

Para configurar o Trigger, pense em quando você quer ver sua checklist. Você pode fazê-la iniciar sempre que abrir o GitHub, mas provavelmente isso não será o que você quer, já que não precisa vê-la quando estiver lendo as perguntas e respostas de outros usuários, ou procurando algo em um repositório.

Eu decidi acioná-la sempre que um botão Create pull request estiver na página, o que é um indicativo de que estou prestes a abrir um pull request. Então, provavelmente é um bom momento para passar pela minha checklist!

Portanto, siga os movimentos de abrir uma PR e navegue até uma página que tenha esse botão verde (enquanto mantém seu editor de páginas aberto).

Depois de ver esse botão, vá até a seção Advanced: Match Rules do bloco Trigger e procure o campo Selectors.

A partir daí, você pode tanto usar o botão da seta do mouse para abrir uma visualização de seletor de elementos e clicar para selecionar o botão, como pode copiar a classe dele diretamente no campo. Precisamos da classe abaixo:

.hx_create-pr-button

Então, agora, você criou um acionador, ele será chamado sempre que você carregar uma página hospedada no github.com.

Bom, já identificamos a classe para esse botão. A parte mais difícil já passou! Agora, só precisamos ocultá-lo, mostrar a checklist e exibi-la novamente quando a lista estiver concluída.

Passo 3 – ocultar o botão Create pull request

Selecione o botão de adição abaixo do bloco Trigger para adicionar outro bloco. Você verá uma janela que permite pesquisar todos os blocos disponíveis. Procure por hide (ocultar) e você verá este bloco.

Passe o mouse sobre o bloco "Hide" (Ocultar) para ver mais opções. Selecione "Add" (Adicionar) para trazê-lo para a sua extensão.

A única configuração que este bloco precisa é saber qual elemento ocultar. Nesse caso, será exatamente o mesmo elemento que usamos em nosso acionador – o botão Create pull request. Assim, você pode copiar essa mesma classe e defini-lo como valor para o seletor.

Passo 4 – abrir uma barra lateral

Adicione agora outro bloco, chamado Show Sidebar. Isso abrirá um painel no lado direito do seu navegador para exibir o conteúdo.

Eu configurei o campo panelHeading para PR para especificar que ele deve carregar a guia PR. Se você ainda não tiver outros painéis laterais configurados, não precisará colocar nada aqui e poderá pular para a próxima etapa.

Passo 5 – atribuir a si mesmo ao issue (problema)

Antes de chegarmos à checklist, adicionei mais uma parte de automação, além de exibir a checklist e ocultar o botão.

Criei uma ação para me atribuir ao problema. É apenas um clique, eu sei, mas por que não fazer os robôs fazerem isso por nós? 😊

Para fazer isso, adicione outro bloco chamado Simulate a DOM event. Este bloco faz exatamente o que diz... ele simula uma ação sobre um elemento específico, como clicar nele.

Atribua um seletor para o elemento com o qual você deseja interagir e também um evento.

Assim como nos blocos de acionamento e ocultação, você pode usar o botão do mouse para abrir um seletor na tela e selecionar o link assign yourself para aplicar automaticamente essas classes ao campo seletor.

Você também pode aplicar manualmente a classe copiando e colando isso no campo selector:

#new_pull_request .js-issue-assign-self

Certifique-se de selecionar click no campo event e estamos prontos!

Passo 6 – criar sua checklist

Agora, estamos no cerne de nossa extensão. Hora de construir a checklist. Selecione o botão de adição e adicione o bloco Show a modal or sidebar form.

Ele exibe um formulário. Para cada item que desejarmos reconhecer ou pensar a respeito antes de enviar uma solicitação PR, criamos uma caixa de seleção.

Definir um título e uma descrição para o formulário

Isso é puramente estético, então você pode fazer como quiser.

Configurar o primeiro campo

Estamos fazendo a nossa checklist ​​antes da abertura do PR. Faremos, então, nosso primeiro campo do formulário. Precisaremos definir os seguintes campos no PixieBrix:

• name (nome)
• label (etiqueta)
• input type (tipo de entrada)

O nome e a etiqueta podem ser o que você quiser. Porém, mantenha o nome simples, pois você precisará fazer referência a ele na próxima etapa ao verificar se é true (verdadeiro) ou false (falso). A etiqueta é o que aparece visualmente ao lado da caixa de seleção. Para o tipo de entrada, marque a caixa de seleção.

Você pode visualizar como está ficando no painel lateral direito do editor de páginas do PixieBrix.

Adicionar o restante dos itens como novos campos

Vá acima do campo para selecionar o botão azul que diz "Add new field" (Adicionar um novo campo) e faça tudo novamente para quantos itens você tiver.

Configuração final do formulário

Está quase pronto! Navegue até a seção abaixo das opções do campo de formulário, que diz Submit Button Text (Texto do botão de envio). Você pode deixar como está. Eu personalizei o meu para Ready to Open (Pronto para abrir) para deixar a ação do botão mais clara.

Mais importante ainda, altere o valor de Location para sidebar em vez de modal. Isso define o formulário de modo que apareça na barra lateral que abrimos na etapa anterior.

Passo 7 – mostrar o botão Create pull request quando a checklist estiver concluída

Adicione um bloco final à extensão chamado Show (Exibir). Ela é semelhante ao bloco Hide (Ocultar), e passaremos para a mesma classe que estamos referenciando para o botão Create pull request.

Aqui está mais uma vez, caso precise relembrar sobre qual estou falando:

.hx_create-pr-button

Há só mais uma configuração a fazer, pois queremos controlar quando este bloco é executado. Queremos mostrar o botão apenas se todos os itens foram verificados no envio do formulário.

Poderíamos somente tornar obrigatório cada campo no formulário para que você não pudesse enviar o formulário até que todos fossem verificados. Mas há uma maneira mais fácil de fazer isso: editar o campo Condition em Advanced Options (Opções Avançadas) neste bloco.

É aqui que você pode especificar quando esse bloco deve ser executado. Você criará uma instrução que retornará true se todos os campos da checklist forem true.

Esta é a aparência da sintaxe, embora você precise trocar o valor do item pelo nome de cada item.

{{ "true" if @form.item1 and @form.item2 and @form.item3 and @form.item4 and @form.item5 and @form.item6 and @form.item7 and @form.item8 and @form.item9 and @form.item10 and@form.item11 }}

Quando terminar, seu bloco deve ficar assim:

Selecione o botão azul salvar no canto superior direito do editor de página PixieBrix para salvar sua extensão.

Faça seus testes

Agora experimente! Se você ativou a extensão pré-compilada do início do artigo, ou se seguiu o tutorial e a construiu por conta própria, você está pronto para testá-la.

Tente abrir um pull request e você verá o formulário da barra lateral e nenhum botão verde. Marque todos os itens da lista e clique em Submit (Enviar) e, de repente, seu botão aparecerá e você já estará atribuído ao PR!

Se você tiver algum problema para começar a construí-lo ou não estiver funcionando como esperado, a comunidade do PixieBrix está ativa e os mantenedores estão sempre dispostos a ajudar.

Porém, se você é mais um aprendiz visual e prefere assistir, criei um vídeo que mostra como criar essa checklist automatizada de PR (em inglês).

Obrigado pela leitura!

Existem muitas ferramentas para automatizar nossos processos de codificação. Nós podemos procurar por erros de sintaxe com ESLint e formatar nosso código com Prettier.

Nem todo mundo na sua equipe se lembrará de rodar todos os comandos toda vez que for feito um commit. Como nós podemos usar o Husky para adicionar hooks do Git e fazer com que eles executem esses comandos para nós?

• O que são os hooks do Git?
• O que é Husky?
• O que nós vamos construir?
• Passo 0: como configurar um novo projeto
• Passo 1: como instalar o Husky em um projeto
• Passo 2: como configurar o Husky para rodar os hooks do Git
• Passo 3: como usar o Husky para formar o código com Prettier

O que são os hooks do Git?

Os Git hooks (ou hooks do Git) são scripts que você pode configurar para rodar em certos eventos no ciclo de vida do Git. Esses eventos incluem diferentes estágios do commit, como antes de um commit (pré-commit) e depois de um commit (pós-commit).

Eles são muito úteis, pois permitem que desenvolvedores rodem processos de código automatizados ou até forcem padrões ao automatizar outros scripts para rodar esses processos.

O que é o Husky?

O Husky é uma ferramenta que nos permite facilmente configurar hooks do Git e executar scripts que queremos em certos estágios.

Ele inclui um objeto dentro do nosso arquivo package.json  que rodará o Husky nos scripts que nós especificarmos. Depois disso, o Husky gerencia os pontos do ciclo de vida do Git em que nossos scripts rodarão.

O que nós vamos construir?

Vamos configurar um projeto simples onde poderemos testar os hooks do Git.

Você pode acompanhar o artigo com qualquer projeto em que você estiver trabalhando. Usarei o Next.js como ponto inicial, simplesmente pelo fato de que precisamos rodar apenas um comando para ter o projeto iniciado.

Uma consideração é que, ao acompanhar com esse projeto, saiba que estaremos usando o Prettier como um exemplo do que você pode fazer com hooks do Git.

O Prettier é uma ferramenta que automaticamente formatará nosso código sem que tenhamos que fazê-lo, o que, se você não estiver se preparando para fazer, pode causar muita tensão. Acompanhar comigo usando o projeto com Next.js vai permitir que você faça testes sem mudanças não intencionais.

Quanto ao teste dos hooks do Git, começaremos adicionando uma instrução simples na linha de comando para ver o Husky funcionando e nós também testaremos a adição do Prettier, que formatará o nosso código automaticamente.

Por fim, enquanto escrevo esse artigo, soube que o Husky lançou uma versão Alpha v7. Considerando que é apenas uma versão Alpha, seguiremos com a v4, que nos permite instalar facilmente o Husky com o npm.

Passo 0: como configurar um novo projeto

Como eu mencionei, você pode seguir os mesmos passos com qualquer projeto gerenciado com um arquivo package.json.

O Next.js é absolutamente algo além do necessário para um passo a passo básico. Porém, o objetivo é minimizar os passos de configuração para focar no trabalho com o Husky.

Para começar com o Next.js, vá até o diretório em que você deseja começar seu projeto e rode o seguinte comando:

yarn create-next-app meu-projeto-com-husky
# ou
npx create-next-app meu-projeto-com-husky

Nota: sinta-se livre para substituir meu-projeto-com-husky pelo nome que você quiser que o seu diretório tenha.

Isso criará uma nova pasta, um novo projeto Next.js, e instalará todas as dependências.

Ao terminar, navegue até aquela nova pasta e podemos seguir em frente!

Acompanhe aqui com o commit.

Passo1: como instalar o Husky em um projeto

Para instalar o Husky, podemos utilizar o yarn ou o npm.

yarn add husky
# ou
npm install husky

Nota: se, ao instalar o Husky nesse momento, a versão instalada for a v7, isso significa que a v7 foi oficialmente lançada. Confira a documentação atualizada do Husky (em inglês) ou instale a última versão da v4 especificando husky@4.3.0 (ou seja qual for a versão mais recente) ao instalar.

Quando o pacote terminar de instalar, podemos seguir com o Husky.

Acompanhe aqui com o commit.

Passo 2: como configurar o Husky para rodar os hooks do Git

Agora, vamos configurar o Husky para conseguir usar nossos hooks do Git.

Dentro do nosso arquivo package.json, crie uma nova propriedade chamada husky com um objeto vazio.

"husky": {},

Você pode, de fato, adicionar essa propriedade onde você quiser no arquivo package.json. Eu, no entanto, a adicionarei logo após a propriedade scripts  para conseguir gerenciá-las juntas mais facilmente.

Dentro da propriedade Husky, adicionaremos outra propriedade chamada hooks, que também contém um objeto vazio:

"husky": {
  "hooks": {}
},

Aqui é onde adicionaremos nossos hooks do Git. O Husky suporta basicamente todos os hooks do Git definidos pelo próprio Git. Então, podemos ser tão flexíveis quanto quisermos dentro do nosso fluxo de eventos do Git.

Para fins de teste, eu criei uma nova branch onde eu literalmente adicionei todos os hooks do Git daquela página, incluindo um script que simplesmente escreve no terminal [Husky] nome do evento.

Nota: você não precisa fazer isso a não ser que esteja curioso. O objetivo é ser capaz de demonstrar a você, com meu exemplo, como funciona.

“husky”: {
  “hooks”: {
    “applypatch-msg”: “echo \”[Husky] applypatch-msg\””,
    “pre-applypatch”: “echo \”[Husky] pre-applypatch\””,
    “post-applypatch”: “echo \”[Husky] post-applypatch\””,
    “pre-commit”: “echo \”[Husky] pre-commit\””,
	}
}

O que isso fará é dizer ao Husky que, em cada etapa na qual temos permissão para nos conectar ao Git, diremos a ele a ação desejada!

Quando eu fizer os commits dessas mudanças, nós poderemos imediatamente ver o Husky disparar alguns de nossos scripts.

Esses são todos eventos aos quais o Git permite que nos conectemos e que acontecem durante o processo de commit.

Do mesmo modo, se eu der um push nessas mudanças para o Github, poderei ver que o processo de push roda o hook pre-push!

Pode ser que nunca usemos a maioria dos hooks que o Husky e o Git proporcionam (vimos apenas alguns deles).

Porém, é realmente incrível ver como isso pode ser poderoso, seja rodando códigos que formatarão o nosso código, evitando que se faça o commit de chaves de acesso secretas sejam commitadas, ou qualquer coisa que possa ajudar a automatizar tarefas importantes do nosso fluxo de trabalho.

Conseguimos ver, agora, que configuramos o Husky ao especificar a configuração e os hooks dentro do nosso package.json.

Acompanhe aqui com o commit.

Nota: se quiser conferir minha branch que inclui todos os testes com hooks do Git, você pode encontrá-la no Github.

Passo 3: como usar o Husky para formatar seu código com Prettier

Finalmente, em um caso mais próximo à realidade, testaremos o Prettier e formataremos nosso código automaticamente.

O Prettier é uma ferramenta de formatação de código que permite limpar o código facilmente, fazendo parecer como se uma única pessoa o tivesse escrito.

Por que ferramentas como o Prettier são importantes? Quando estamos programando, especialmente em equipe, é importante manter a consistência para que todo mundo saiba o que esperar. Isso evitará discussões sobre um ponto e vírgula em uma code review, mas também ajudará a identificar erros de sintaxe e a prevenir bugs.

Atenção: rodar o Prettier formatará automaticamente todo o código. Por enquanto, estamos testando isso antes de fazer o commit das mudanças. Assim que você aplicar isso a um Git Hook, ele automatizará esse processo.

Para começar, vamos instalar o Prettier com nosso gerenciador de pacotes:

yarn add prettier -D
# ou
npm install prettier --save-dev

Nota: estamos instalando o Prettier como uma devDependency, já que sua aplicação não precisa disso para rodar.

Depois, podemos adicionar um novo script ao nosso package.json que facilitará rodar o Prettier para fazer os testes.

Dentro da propriedade scripts, adicione:

"lint": "prettier --check ."

Para começar, rodaremos o primeiro teste na modalidade "check", o que nos permite ver quais arquivos seriam alterados.

Execute o seguinte comando:

yarn lint
# ou 
npm run lint

Assim que o fizermos, poderemos perceber que o Prettier nos dirá quais dos arquivos listados serão alterados.

Nesse ponto, nosso código se manterá inalterado. Se quisermos que mudanças reais sejam feitas, primeiros temos que incluir um script adicional:

"format": "prettier --write ."

Se rodarmos esse script, ele atualizará todos aqueles arquivos mencionados de acordo com a especificação do Prettier.

Atenção: executar o Prettier para realizar as mudanças fará alterações em seus arquivos. Todas essas alterações são apenas para fins de adequação de estilo e não deveriam impactar o modo como seu código é executado, apenas a aparência dele. Antes de formatar, é prudente salvar todas as suas mudanças através de um commit no Git, de maneira a poder reverter facilmente essas mudanças caso não esteja feliz com elas.

Você agora pode rodar o script com:

yarn format

E podemos ver que o Prettier atualizou seus arquivos!

Agora, a parte que é relevante nessa jornada: podemos adicionar isso como um hook do Git. Dessa maneira, quando alguém tentar realizar um commit em um código, o Prettier executará antes de o código ser salvo. Isso significa que sempre manteremos um código consistente, com o Prettier formatando o estilo.

Dentro de nossa configuração dos hooks no Husky, vamos adicionar:

"husky": {
  "hooks": {
    "pre-commit": "prettier --write . && git add -A ."
  }
},

Como você pode perceber, no nosso hook pré-commit, também estamos adicionando git add -A ..

Quando o Husky for executado, ele simplesmente executará o script fornecido. Ao rodar o comando do Prettier, estamos apenas formatando o código, mas ainda faltaria salvar essas mudanças como parte do processo. Por isso, usaremos git add para guardar todas essas mudanças e incluí-las no commit.

Para fins de teste, eu reverti as mudanças de todos os arquivos formatados antes. Se você estiver acompanhando com o mesmo projeto, você pode executar o seguinte comando:

git checkout pages

Essa ação apagará todas as mudanças em pages para o último commit.

Agora, vamos testar adicionar todos os nossos arquivos com Git e fazer o commit dessas mudanças.

Tendo executado o comando de commit, podemos ver que o hook pré-commit do Husky já fez seu trabalho e formatou nosso código.

Acompanhe aqui com o commit.

O que eu posso fazer depois?

Use lint-staged para formatar somente os arquivos modificados

Estamos usando o Prettier no nosso hook pré-commit e especificando ., o que significa rodar em todos os arquivos todas as vezes.

Podemos usar uma ferramenta chamada lint-staged, que ainda nos permite rodar nossos hooks do Git com o Husky, executando-o apenas naqueles arquivos que estão em stage no Git.

Por exemplo, se quiséssemos fazer isso com o Husky e o Prettier, nossa configuração se pareceria com algo do tipo:

"husky": {
  "hooks": {
    "pre-commit": "lint-staged"
  }
},
"lint-staged": {
  "*": "prettier --write"
},

Como parte de como lint-staged é executado, ele anexará as mudanças dos arquivos alterados ao final de nossa instrução para o Prettier automaticamente.

Você também perceberá que não incluímos git add. O lint-staged também adicionará quaisquer mudanças ao Git instantaneamente para nós.

Personalize a configuração do Prettier para formatar as regras

O Prettier é bem opinativo. Há algumas coisas das quais eu, pessoalmente, não gosto e talvez você concorde comigo.

Felizmente, o Prettier permite a você configurar um arquivo que pode sobrescrever algumas regras para fazer com que seu código seja do jeito que você e seu time queiram.

Diga ao Prettier para ignorar arquivos com .prettierignore

Você provavelmente não quer o Prettier rodando em "tudo" (bem, talvez sim).

O Prettier permite que você configure um arquivo .prettierignore  dentro da raiz do seu projeto, próximo ao package.json, de modo similar ao .gitignore, que possibilita a você dizer ao Prettier quais arquivos ele não deve monitorar.

• Siga o autor no Twitter
• Inscreva-se no canal do YouTube do autor
• Inscreva-se para receber a newsletter do autor
• Patrocine o autor