FreteBras web dev flow 2.5

Já faz algum tempo que em nossas squads estamos adotando para os novos projetos de software o “GitHub flow”, que é um fluxo de trabalho leve e baseado em branch que suporta equipes e projetos em que as implantações são feitas com regularidade.

Link para a versão 2.0!

Este guia explica como e porquê esse fluxo de apenas sete passos se adere ao nosso modelo de trabalho atual, que não exige necessidade de um plano de releases a fim de manter múltiplas versões de um serviço em ambiente de produção, junto ao crescimento contínuo do nosso time de engenheiros geograficamente distribuídos.

1 — Criar um branch

Quando você estiver trabalhando em um projeto, terá várias idéias diferentes em andamento a qualquer momento, algumas das quais estão prontas para serem usadas e outras que não. As branchs existem para ajudá-lo a gerenciar esse fluxo de trabalho.

Ao criar um branch em seu projeto, você cria um ambiente em que pode experimentar novas idéias. As alterações feitas em um branch não afetam a ramificação master; Portanto, você pode experimentar e commitar alterações, seguro de que sua branch não será mesclada até que esteja pronta para ser revisada por alguém com quem você está colaborando.

git checkout -b refector_r1h1-refatora-autenticacao

Branching é um conceito central no Git, e todo esse fluxo é baseado nele. Há apenas uma regra: qualquer coisa na ramificação master é sempre implantável, portanto não deve conter código quebrado, testes falhando e muito menos credenciais de acesso.

Por isso, é extremamente importante que seu novo branch seja criado fora do master ao trabalhar em um recurso ou uma correção. O nome do seu branch deve ser descritivo, separando palavras por “-”, (por exemplo: refactor_r1h1-refatora-autenticacao, feat_r1h2-cria-avatares-resolucao-retina), para que outros possam ver e compreender o que está sendo trabalhado.

Dicas para nomear seu branch seguindo o conceito tipo_ESCOPO:

• feat — será implementada uma nova funcionalidade
• fix — será implementada uma correção para resolver um problema existente
• refactor — será realizado algum refactor em parte do código que já funciona
• chore — será implementa alguma melhoria de código e/ou infraestrutura
• test — será desenvolvido algum novo cenário de teste para a aplicação
• doc — será feita alguma mudança na documentação

2 — Adicionar commits

Depois que seu branch for criado, é hora de começar a fazer suas alterações. Sempre que você adiciona, edita ou exclui um arquivo, você deve fazer um commit e adiciona-lo ao seu branch. Esse processo de adição de commits acompanha o seu progresso enquanto você trabalha em uma feature-branch.

Os commits também criam um histórico transparente do seu trabalho para que outras pessoas possam seguir e entender o quê, e, porquê você as fez. Cada commit tem uma mensagem de confirmação associada, que é uma descrição que explica porque uma alteração específica foi feita. Além disso, cada commit é considerado uma unidade de mudança separada. Isso permite reverter as alterações se um erro for encontrado ou se você decidir seguir um caminho diferente.

Conventional Commits: uma especificação para adicionar significado legível por humanos e por máquina para commitar mensagens.

O conventional commits é uma estrutura utilizada para padronizar as mensagens de commit, ele funciona a partir da seguinte estrutura:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)] 

No type é informado o tipo de alteração que está sendo realizada. Os tipos existentes, são os declarados no Conventional Commits (fix, feat) e no Commitlint ( ‘build’, ‘chore’, ‘ci’, ‘docs’, ‘feat’, […]) cada um com o seu devido significado.

No body não existe uma convenção exata, somente que o mesmo é opcional, entretanto quando existir, deve ser descritivo quanto ao que foi feito.

No footer também não existe uma convenção exata, entretanto é comumente utilizado para descrever avisos e vincular atividades do JIRA por exemplo.

O scope é uma parte opcional na qual é possível referenciar, entre parênteses e usando um substantivo, uma parte do código, como um módulo.

Ex: fix(Company): fix company registration bug

Esse exemplo basicamente diz que foi feito uma correção no módulo de empresa para concertar um bug do cadastro.

A description conforme já apresentado, se trata de uma descrição clara e objetiva do que foi feito.

Fonte: Conventional Commits

Dicas gerais:

• Faça commits com seu email da FreteBras;
• Mantenha o .gitignore consistente com as mudanças no seu ambiente;
• Não permita credenciais de acesso vazarem no código fonte;
• Não versione arquivos gerenciados como dependência;
• Não versione arquivos de configuração;
• Não versione arquivos gerados automaticamente;
• Estude os tipos corretos para escrever seus commits.

ProTip

As mensagens de commit são importantes, principalmente porque o Git rastreia suas alterações e as exibe como confirmadas quando são enviadas ao servidor. Ao escrever mensagens claras de commit, você pode facilitar o acompanhamento e feedback de outras pessoas.

Você sempre pode discriminar melhor a solução implementada nas mensagens de commit. 🤩

3 — Abrir um Merge Request

Um Merge Request (MR) permite iniciar discussões e colaborações sobre seus commits. Como esses MR’s estão totalmente integrados ao repositório Git subjacente, qualquer membro do time pode ver exatamente quais alterações seriam mescladas se aceitarem sua solicitação.

Você pode abrir um MR a qualquer momento durante o processo de desenvolvimento:

• Quando você tem pouco ou nenhum código, mas deseja compartilhar algumas capturas de tela ou idéias gerais.
• Quando está bloqueado criativamente e precisa de ajuda ou aconselhamento.
• Quando está pronto para que alguém revise seu trabalho.

Usando o sistema “@menção” no seu MR, você pode solicitar feedback de pessoas ou equipes específicas, estejam elas no final do corredor ou em até outro fuso horário.

Dicas para abrir um MR:

• Atualize seu branch master local:
  git checkout master, git pull --rebase. *1
• No seu feature-branch, efetue o rebase com o head do master:
  git checkout refactor_r1h1-refatora-autenticacao, git rebase master
• Só então abra o MR.

O rebase em sua forma padrão de uso, permite que suas alteração sejam realocadas adiante no histórico, recebendo todas as alterações isoladas no seu branch e alinhando-as como se acontecessem após as revisões atualizadas do master, sem as complicações de um reverse merge, alem de deixar o histórico mais limpo e linear.

Na descrição do seu MR, tente adicionar a maior quantidade de informação possível. Descrições detalhadas de MR's contribuem com:

• Code Review: Seus companheiros de equipe precisaram fazer menos esforço para entender o porque dessa atividade estar sendo desenvolvida e o racional para suas escolhas;
• QA: Quando você faz um MR detalhado, o time de QA consegue imaginar e produzir testes com maior facilidade. Dessa forma, caso você crie end points, documente rotas, payloads, códigos HTTPs retornados, responses de sucessos e falhas etc. No caso do front end, prints e descrições de fluxos podem ajudar;
• Documentação: Ótima forma de documentar o que foi, como, por quem, quando e como era o código inicialmente. Assim, descreva a mensagem do MR da melhor forma possível.

ProTip

MR são úteis para contribuir com projetos e para gerenciar alterações em repositórios, pois fornecerá uma maneira de notificar os mantenedores sobre as alterações que você deseja que eles considerem antes de serem mescladas no branch principal.

Não está feliz com o histórico gerado por sua revisão?

Considere realizar um squash para comprimir os vários commits em um só e manter o histórico mais limpo e reversível.

Entretanto cuidado, pois modificações no histórico geram novos identificadores e podem exigir reenvio forçado (git push --force)*3 dos seus commits, por isso deve ser usado apenas em branchs no qual você é o proprietário.

4 — Discutir e revisar seu código

Depois que uma MR é aberta, a pessoa ou equipe que está revisando suas alterações pode ter perguntas ou comentários. Talvez o estilo de codificação não corresponda às diretrizes do projeto, esteja faltando algo nos testes unitário ou talvez tudo esteja ótimo e tudo esteja em ordem.

As MR são projetadas para incentivar e capturar esse tipo de conversa.

Se alguém comentar que você esqueceu de fazer algo ou se houver um erro no código, você poderá corrigi-lo em seu branch e simplesmente efetuar a alteração. O repositório mostrará seus novos commits e qualquer feedback adicional que você receber na tela de visualização de MR.

Chame os diversos times para colaborar e não centralize somente aos Devs!

ProTip

Os comentários do MR são escritos em Markdown, para que você possa incorporar imagens, emojis (🤩), usar blocos de texto pré-formatados e outras formatações leves.

5 — Deploy

Você pode realizar a implantação (deploy) a partir de um branch para teste final de produção antes de mesclar no master.

Depois que seu MR for analisado e o branch passar nos testes automatizados, você poderá implantar suas alterações no ambiente de staging. Se seu branch causar problemas, você poderá recuperá-lo implantando o master existente na produção.

6 — Merge

Agora que suas alterações foram verificadas na produção/staging, é hora de mesclar seu código no branch principal.

Depois de mesclados, as MR preservam um registro das alterações históricas no seu código. Por serem pesquisáveis, permitem que alguém volte na linha do tempo para entender porque e como uma decisão foi tomada.

Ao mesclar manualmente seu branch no master, use a opção --no-ff *2 para gerar um merge commit. Dessa maneira, você facilita o rastreamento, visualização e também a reversão dos recursos incrementados.

• git checkout master
• git merge --no-ff refactor_r1h1-refatora-autenticacao

7 — Pós Merge

Após realizar o merge, começa a etapa de monitoramento, ferramentas como Flare, Bugsnag ou Instabug facilitam na hora de identificar se o que foi desenvolvido está causando algum problema em produção. Lembre-se, máquinas não erram mas você não é uma máquina e você que fez o código…

Por exemplo, ferramentas de gerenciamento de desempenho de aplicativos (APM) ajudam a você entender se a quantidade de chamadas com sucesso abaixaram ou se a latência aumentou. Problemas comuns:

• Usuários podem acessar sua plataforma de diferentes máquinas;
• Chamadas para seu sistema vão ocorrer de dispositivos com N versões e tipos;
• Podem acontecer chamadas em uma volumetria que o código não está preparado para responder e uma série de coisas…

Portanto, monitore e remova o código de produção se necessário!

ProTip

Ao incorporar determinadas palavras-chave no texto da sua solicitação de recebimento, você pode associar problemas ao código. Quando sua MR é mesclada, os problemas relacionados também podem ser fechados. Por exemplo, ao digitar a frase “Closes #123” você encerraria o issue/task de número #123 no repositório.

* — Dicas extras de configuração

*1) Sempre que precisar mesclar atualização upstream em seu feature-branch, faça-o com --rebase, a menos que haja mais pessoas trabalhando no mesmo branch (nesse caso, discuta quando será o melhor momento), ou se já houver um MR em aberto.

*2) Para garantir que você não se esqueça de adicionar --rebase ao fazer o pull e --no-ff durante o merge, é recomendado pré-definir essas configurações globalmente:

• git config --global pull.rebase true
• git config --global merge.ff fase

*3) Ao trabalhar em um branch compartilhado evite o force-pushing, entretanto caso seja realmente necessário, utiliza a opção --force-with-lease, evitando assim substituir o trabalho de outra pessoa.

*4) Nunca realize o --rebase em commits que já existiram em qualquer lugar, exceto no seu repositório local. Nesse caso opte pelo uso do merge.

Obrigado por ler! Se você gostou do artigo, dê um clap 👏.