Como criar uma checklist de pull request automatizada no GitHub

Artigo original: How to Create an Automated Pull Request Checklist in GitHub

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!