🏷 GitFlow

Introdução

Nesta seção, explicaremos os padrões de fluxo de trabalho que utilizamos para gerenciar projetos utilizando Git. Acompanhar esses padrões nos ajuda a manter uma boa organização e facilita a comunicação entre os membros da equipe. Além disso, esses padrões nos permitem criar um histórico de alterações coerente e fácil de entender, o que é fundamental em projetos de software. Vamos explicar como funciona o processo de desenvolvimento, homologação e release de projetos, bem como os padrões de branchs, commits e pull requests que utilizamos.

Usamos uma variação do Git Flow em conjunto com o Conventional Commits e o Versionamento Semântico para criar o fluxo de trabalho em nossos projetos. É importante ler os artigos sobre esses temas para entender completamente como eles são utilizados em nosso fluxo. Neste artigo, abordaremos apenas as implementações específicas que fazemos e um resumo desses conceitos.

Fluxo

É recomendado ler o artigo sobre Git Flow para total coompreensão dos padrões aplicados.

Nosso fluxo sempre começa da branch main, ela se refere ao código que está em produção.

A partir da branch main temos a branch de homologação ou QA, aqui chamada de homolog. É da branch de homologação que saem as releases e versões novas do projeto. É da branch de homolog que os colaboradores criam suas ramificações de trabalho que, após concluídas, são mergeadas novamente na homolog para que então, na janela de deploy, seja criada a release e mergeada na main, onde o código irá entrar em produção.

Branches de correções que têm prefixado fixe são criadas a partir da main e mergeadas tanto na main quanto na homolog seguindo as práticas de versionamento semântico.

O seguinte diagrama exemplifica esse fluxo de branchs nos projetos.

%%{init: { 'logLevel': 'debug', 'gitGraph': {'showCommitLabel': false}} }%%

gitGraph
    commit
    branch fixe
    branch homolog
    checkout homolog
    commit
    branch feat-189
    commit
    checkout homolog
    commit
    branch feat-394
    commit
    checkout homolog
    merge feat-394
    checkout feat-189
    commit id: "add"
    checkout fixe
    commit
    checkout main
    merge fixe
    checkout homolog
    merge feat-189
    merge fixe
    checkout main
    merge homolog
    commit
    commit

Loading

Versionamento Semântico

É recomendado ler o artigo sobre Versionamento Semântico para total coompreensão dos padrões aplicados.

O versionamento Semântico é uma técnica de versionamento de software que segue uma estrutura de três números (MAJOR.MINOR.PATCH). Cada um desses números tem um significado específico, conforme as alterações realizadas no código.

MAJOR: é a primeira parte do número de versão e indica mudanças significativas no código, que podem afetar a compatibilidade com versões anteriores.

MINOR: a segunda parte do número de versão indica adição de novas funcionalidades ao código, mantendo a compatibilidade com versões anteriores.

PATCH: a terceira parte do número de versão indica correções de bugs e outras pequenas alterações no código, sem afetar a compatibilidade com versões anteriores.

Na Dump, atualizamos a versão MINOR sempre que uma nova release sobe de homolog para main. Já para casos de correções de bugs em produção, sempre que subimos da branch fixe para main atualizamos a versão PATCH. Isso nos permite manter o controle e organização das versões do projeto, facilitando identificar e corrigir possíveis problemas.

Versoões MAJOR são somente atualizadas em lançamentos solidos de projetos em produção ou troca de framework onde a compatibilidade com verões mais antigas é perdida.

O seguinte diagrama exemplifica esse fluxo de versionamento nos projetos.

%%{init: { 'logLevel': 'debug', 'gitGraph': {'showCommitLabel': false}} }%%

gitGraph
    commit tag: "release 0.0"
    branch fixe
    branch homolog
    checkout homolog
    commit
    branch feat-456
    commit
    checkout homolog
    commit
    branch refactor-423
    commit
    checkout homolog
    merge refactor-423
    checkout feat-456
    commit id: "add"
    checkout fixe
    commit
    checkout main
    merge fixe tag: "release 0.0.1"
    checkout homolog
    merge feat-456
    merge fixe
    checkout main
    merge homolog tag: "release 0.1"
    checkout homolog
    commit
    commit
    branch feat-321
    commit
    commit
    commit
    checkout homolog
    merge feat-321
    commit
    checkout main
    merge homolog tag: "release 0.2"
    commit
    commit
    commit

Loading

Convenção de Projeto

Padrões de projeto são essenciais para a organização e qualidade de um projeto. Eles fornecem uma estrutura comum para todos os colaboradores do projeto seguirem, garantindo que todo o código esteja no mesmo formato e seguindo as mesmas convenções. Isso facilita a manutenção e o desenvolvimento futuro do projeto, pois todos os colaboradores estarão familiarizados com a estrutura e os padrões utilizados.

Além disso, os padrões de projeto também ajudam a garantir que o projeto seja escalável e fácil de entender para novos colaboradores. Isso é especialmente importante em projetos de grande escala ou em equipes de desenvolvimento distribuídas.

Nesta seção, abordaremos os padrões de commits, branchs e pull requests. Esses padrões são cruciais para manter o histórico de alterações do projeto organizado e compreensível para todos os colaboradores. Também discutiremos os padrões de repositório, incluindo a estrutura de pastas e scripts de automação.

Padrões de Repositorio

É importante seguir alguns padrões nos nossos repositórios para manter a organização e facilitar a troca entre projetos.

Nomes de repositórios

Para projetos de clientes, recomendamos que os nomes dos repositórios comecem com o prefixo do cliente, seguido pelo nome do projeto. Por exemplo: fipo-<nome-do-projeto>. Dessa forma, fica mais fácil identificar os projetos de cada cliente e facilitar a troca entre eles.

Documentação e informações

Todos os repositórios devem ter um arquivo README que informe sobre a finalidade do projeto, as tecnologias utilizadas e como subir e testar o projeto em ambiente local. Além disso, toda a documentação, fluxogramas e desenhos de arquitetura devem estar na pasta docs.

Scripts e automação

Para facilitar o uso e o gerenciamento do código do repositório, recomendamos que scripts para automatizar processos, como testes, atualização de dependências e subida do projeto, estejam na pasta bin. É aconselhável ter um script bash chamado build-and-up.sh que faça a subida e configuração do ambiente automaticamente.

Outra recomendação é evitar depender do host do colaborador ao utilizar ferramentas, APIs ou serviços, e utilizar o Docker para garantir a integridade do projeto entre colaboradores e máquinas.

Padrões de Branch's

As branch's devem ser nomeadas com o padrão <id-issue>-<titulo-issue> onde <id-issue> é o número da issue associada na ferramenta de organização de tarefas (atualmente o Jira) e <titulo-issue> é o título da issue. Atualmente, não há um consenso se o nome da branch deve ser em inglês ou em português, mas é importante lembrar que toda branch de atuação deve ter uma issue associada. Exceto pelo <id-issue>, o resto do nome da branch deve ser em minúsculo e sem caracteres especiais. Isso ajuda a manter uma organização consistente e fácil de rastrear.

Exemplos

• DETR-166-implementar-fila-por-status-na-execucao-da-rotina-de-tarefas
• FILX-321-corrigir-bug-carrinho
• ERTA-41-otimizar-consulta-banco-dados

Padrões de Commits

É recomendado ler o artigo original do Conventional Commits para total coompreensão.

Conforme a documentação do Conventional Commits, Commits Semânticos são uma convenção simples para ser utilizada nas mensagens de commit. Essa convenção define um conjunto de regras para criar um histórico de commit explícito, facilitando a criação de ferramentas automatizadas.

Esses commits auxiliarão você e sua equipe a entenderem de forma facilitada quais alterações foram realizadas no trecho de código que foi commitado. Isso é feito atraves de palavras-chave que vão informar a categoria ou tipo daquele commit, por exemplo.

A mensagem do commit deve ser estruturada da seguinte forma:

<tipo>[escopo opcional]: <descrição>

[corpo opcional]

[rodapé(s) opcional(is)]

Abaixo uma tabela dos tipos prefixados que a Dump usa, eles informam a intenção do seu commit.

Tipo	Descrição
feat	Adiciona um novo recurso ou biblioteca. (se relaciona com o MINOR do versionamento semântico).
fix	Corrigindo um bug ou problema inesperado. (se relaciona com o PATCH do versionamento semântico).
docs	Mudanças ou adição na documentação do projeto, como por exemplo, atualizações em fluxogramas ou desenhos de arquitetura. (Não inclui alterações em código).
test	Mudanças ou adição de testes no projeto. Isso inclui tanto a criação de novos testes quanto a alteração de testes existentes. (Não inclui alterações em código).
build	Mudanças ou adição na configuração do build, como arquivos de configuração ou scripts de compilação. (Não inclui alterações em código).
refactor	Mudanças no código que não incluem adição de novas funcionalidades ou correção de bugs. Pode incluir ajustes de performance, limpeza de código, refatoração de código existente ou remoção de dependências desnecessárias.
ci	Alterações na configuração de integração contínua (CI). (Não inclui alterações em código)
revert	Revertendo uma alteração anterior, devendo acompanhar os hashes dos commits revertidos.

Recomendações

• Use um título consistente com o conteúdo;
• Mantenha a mensagem de commit dentro dos 72 caracteres;
• Recomendamos que na primeira linha deve ter no máximo 4 palavras;
• Forneça detalhes sobre o commit na descrição caso necessário;
• Use links autênticos, sem encurtadores ou afiliados;
• Se estiver revertendo um commit anterior, lembre-se de incluir os hashes dos commits revertidos;
• Se possivel, escreva a mensagem de commit em inglês;
• Use a ortografia e gramática corretas para facilitar a leitura e compreensão da mensagem;
• Mantenha a consistência com as mensagens de commit anteriores para manter uma história coerente do projeto;

Exemplos de mensagens

• feat: add new feature to search bar
• fix: fix issue with search bar not displaying results
• docs: update documentation for search bar usage
• test: add test cases for search bar feature
• build: update build configuration for search bar feature
• refactor: refactor search bar code for performance improvements
• ci: update CI configuration for search bar tests
• revert: revert previous commit that introduced bug in search bar

Padrões de Pull Request

Todos os pull requests são abertos na ferramenta de gerenciamento de projetos utilizada, atualmente o GitHub. Pull requests para novas funcionalidades devem ser abertas a partir da branch de homolog. Utilizamos o método squash em pull requests para homologação, de modo a centralizar as alterações que vieram a partir de uma issue.

Os pull requests abertos para homologação devem seguir o padrão <tipo>: <título-issue> #<id-issue> (#<número-pull-request>) e não devem ultrapassar 72 caracteres. Pode ser necessário resumir o título da issue para se adequar a esse limite.

As atualizações do ambiente são realizadas em janelas específicas de cada projeto, que são definidas com o cliente para determinarmos os melhores períodos para essas atualizações. Esses pull requests de homologação para produção são nomeados no seguinte padrão: "release <número-release> (#<número-pull-request>)". Esses pull requests são realizados com merge request para preservar a lista de alterações. PRs de fixe devem seguir esse mesmo padrao.

Recomendamos que os pull requests de release também contenham uma descrição com o intervalo de tempo das alterações e uma lista do Change log.

Exemplo de pull request para homologação homolog

debit: criar componente de view chamado printing #DETR-463 (#386)

Exemplo de pull request para produção main

release 0.56 (#393)

Intervalo
De: 7/Março/2022
Até: 26/Abril/2022

Change log
- Adicionado suporte a Redis no desenvolvimento local (FIPO-529)
- Adicionado botão de pesquisa na barra de navegação (FIPO-519)
- Criado provedor para implementação de nova macro "whereContains"
- Criada rota de pesquisa

Exemplo de pull request de correção fixe para produção main

release 0.56.6 (#401)

- Corrigido problema com botões que não estavam funcionando corretamente (FIPO-549)