Ferramentas e automações para facilitar a contribuição em seus projetos.

Utilizo algumas ferramentas para facilitar a colaboração e o onboarding de novos desenvolvedores nos meus projetos e quero compartilhá-las aqui.

A idéia é apresentar os itens e a motivação de cada um deles.

TL;DR:

Em meus projetos tenho utilizado algumas ferramentas desde o momento zero para facilitar o onboarding de outras pessoas e evitar os erros desnecessários na execução do projeto.

Versionamento, scripts para rodar as tarefas, hooks do git com verificações relevantes, Docker e arquivos .md têm facilitado lidar com os multiplos projetos.

Conteúdo:

Git e GitHub

No começo do projeto fazemos mudanças grandes e cair em uma versão instável é bem fácil.

Para evitar ter problemas com isso começo o projeto configurando o versionamento dele e fazendo commits frequentes para ter "checkpoints", mesmo que eu faça o squash desses commits depois.
Crio um repositório vazio no github e clono localmente.
Utilizo o github client para fazer isso, mas também é possível fazer isso na interface web e no aplicativo desktop.

Com o client, utilizo o comando

gh repo create <nome do projeto> -d <descrição do projeto> --private -c -g <linguagem que será utilizada>

que tem a seguinte função:

gh repo create digo ao cliente que estou tentando criar um repositório;

<nome do projeto> coloco o nome do projeto;

-d <descrição do projeto> coloco uma linha de descrição para facilitar o entendimento do que se trata o projeto;

--public determino a visibilidade do projeto, podemos ainda utilizar o --private ou --internal;

-c faço o checkout local do projeto;

-g <linguagem> gera o repositório com um .gitignore adequado à linguagem utilizada.

Commitizen

O histórico de commit é uma coisa bem importante para entender a história do projeto e também para orientar sobre o que se trata aquela mudança. Porém acho bem difícil escrever uma boa mensagem de commit.

Para resolver isso configuro no projeto o commitizen.

O Commitizen é uma aplicação que utilizo para facilitar o uso de commits semânticos no projeto.

Ao utilizar o cz commit ele me mostra uma série de questões que respondidas se tornarão a mensagem de commit.

Primeiro o tipo de commit, se é uma feature, a correção de um bug, um refactoring, etc.
Depois os arquivos afetados por aquele commit.
Logo em seguida a ação daquele commit, se há uma quebra de versão ali, e o rodapé.
Com essas informações a postos ele cria a mensagem de commit e mantém o versionamento Semântico do projeto.

Pre-commit

Algumas verificações são fundamentais no desenvolvimento e geralmente falhamos em lembrar delas todas as vezes antes de fazer um commit, então utilizo o pre-commit para fazer essas verificações.
A mensagem de commit está de acordo com o padrão? A formatação também está? Os testes estão passando? Estou commitando alguma chave ou token para o repositório? Essas são algumas coisas que utilizo o pre-commit para evitar errar.

O Pre-commit é um cliente de configuração de hooks pre-commit como diz o nome.
Nas minhas aplicações sejam frontend ou backend configuro desde o primeiro momento, a verificação de mensagem semântica, a verificação de formatação do projeto, a verificação de testes passando, e a verificação se algum tokens ou senha está sendo adicionada ao commit.

Makefile

Decorar comandos de múltiplas linguagens ou até de códigos para múltiplas plataformas pode ser uma barreira de entrada para pessoas mais novas no mundo da programação. Padronizar o jeito de rodar os comandos em nossos sistemas pode ser um começo da melhora do onboarding e da transição das pessoas entre repositórios e plataformas.

Para isso, utilizo o makefile nos projetos.
O Makefile é um arquivo de configuração para rodar scripts no sistema.

Com o makefile configurado, não importa se estou trabalhando com uma linguagem da JVM utilizando Gradle ou Maven, com GoLang, com ReactJS ou NodeJS utilizando npm ou yarn, em todos esses casos consigo configurar uma regra test que roda os testes da minha aplicação.

Logo após essa configuração testar a aplicação é questão de rodar um make test.

Também podemos encadear regras para ações mais complexas. Assim, tarefas custosas com n commandos a serem decorados podem ser trocados por uma linha de execução com autocomplete.

O Makefile funciona em MacOS e Linux. Imagino que também funcione no WSL do Windows.

EditorConfig

Ao revisar mudanças no código, sejam em commits ou pull-requests alterações de formatação podem tornar a leitura mais difícil.

Para amenizar esse problema utilizo o EditorConfig para padronizar a formatação de código, fazendo assim a visualização da diferenciação de código (para um pull request ou até verificação de algum bug) ficar mais fácil.

Readme

Chegar a um projeto novo e não saber do que se trata, por onde começar a olhar o código, como rodar o projeto ou seus testes pode atrasar quem esteja precisando utilizar um projeto como dependência ou até alterar uma feature nele.

Para mitigar esse problema, também no início do projeto, crio um readme para explicar o projeto.

As sessões que costumo utilizar são:

• O que é o projeto e que problema resolve;
• A Arquitetura e as dependências do projeto;
• Como configurar o ambiente para codar ele;
• Como rodar as principais funções do projeto (o Makefile facilita aqui, já que a maioria dos meus projetos seguem um padrão).

Docker e Docker compose

Mesmo sabendo do que se trata o projeto, instalar várias dependências, criar os bancos de dados necessários e tudo mais que é necessário ao setup do projeto pode ser um problema para quem está desenvolvendo em múltiplas stacks.

Para resolver isso, começo o projeto com um docker-compose.yml que rode as dependências, incluindo outros serviços internos e exiba as portas necessárias para a aplicação.

Assim será possível rodar a aplicação tanto dentro do Docker quanto na minha IDE, utilizando as dependências rodando no que estão rodando no docker.

Github Templates

Saber quais são os requisitos de um time para aceitar um novo código em seu repositório ou até quais os dados que utilizam para investigar problemas não é muito fácil no GitHub.Informações no README podem ajudar, mas estão perdidas no meio de outras informações.

Para resolver isso costumo utilizar a feature de templates do Github para criar padrões de documentação dos PRs e Issues, facilitando assim caso alguém fora do time queira contribuir nesse repositório ou submeter um problema para correção.

Conclusão

Acredito bastante nos padrões para facilitar o trabalho entre membros do time e até entre times. Utilizo essas ferramentas para facilitar a comunicação e evitar erros da minha parte ou de outras pessoas do time.
Essas ferramentas facilitam bastante o trabalho tornando a colaboração algo mais fluído.

Utilizem os comentários para sugerir coisas que estão na lista ou vantagens/desvantagens das coisas que estão na lista.