Adaptar Changelog para Evitar Conflitos de Merge em Mudanças Simultâneas

[camilamaia]

Contexto

Atualmente, o changelog do projeto é mantido em um único arquivo, o que frequentemente causa conflitos de merge quando múltiplos colaboradores estão alterando o arquivo simultaneamente. Isso se torna especialmente problemático quando as alterações ocorrem nas mesmas categorias de mudanças (ex.: "features", "bug fixes"). O arquivo atual segue as diretrizes do Keep a Changelog e deve continuar seguindo essas diretrizes para garantir consistência e organização no histórico de mudanças.

Motivação

Para facilitar a colaboração no changelog e evitar conflitos de merge, precisamos de uma abordagem que permita que múltiplos colaboradores possam contribuir de forma independente, sem interferir nas mudanças dos outros. A solução deve ser eficiente, garantindo que o arquivo final de changelog seja bem estruturado e atualizado sem conflitos, e que o padrão atual seja mantido.

Propostas de Solução

Aqui estão duas soluções possíveis para resolver o problema de conflitos no changelog:

• Separação por arquivos
• Coleta de mudanças diretamente dos commits

1. Separar Changelog por Versão, Tipo de Mudança e Nome do Contribuidor

Como funciona:

• A estrutura do changelog seria organizada da seguinte maneira:
  • Para cada versão, seria criada uma pasta por versão (ex.: changelogs/v2.2.0/).
  • Dentro dessa pasta, seria criado um arquivo individual para cada tipo de mudança + usuário. O nome do arquivo incluiria o tipo de mudança e o nome do usuário responsável pela contribuição, como por exemplo:
    • changelogs/v2.2.0/add-camilamaia.md (para uma nova feature adicionada por camilamaia)
    • changelogs/v2.2.0/fix-joaosilva.md (para uma correção de bug feita por joaosilva)

Vantagens dessa abordagem:

• Evita conflitos de merge 100%: Como cada contribuição seria feita em um arquivo separado, com um nome único para cada tipo de mudança e usuário, não haveria sobreposição de edições, mesmo se múltiplos colaboradores estiverem trabalhando nas mesmas categorias ou versões.
• Clareza no histórico de mudanças: As contribuições ficam claramente identificadas pela versão, tipo de mudança e usuário, facilitando o rastreamento e a revisão.
• Organização eficiente: O changelog ficaria estruturado de forma organizada por versão e tipo de mudança, garantindo que cada contribuição seja registrada de maneira clara.

Automação necessária:

• Criar uma automação (usando GitHub Actions) para consolidar os arquivos criados em uma versão em um único arquivo de changelog final, unificando as contribuições feitas para aquela versão.
• A automação poderia gerar ou atualizar o changelog final da versão, combinando as entradas de todos os arquivos na pasta correspondente (ex.: changelogs/v2.2.0/), mantendo a ordem cronológica das mudanças.

2. Padronização de Commits e Automação para Verificar Mudanças no Changelog

Como funciona:

• A proposta é garantir que cada contribuição ao changelog seja identificada no commit com a padronização dos tipos de mudança e usuário.
• O commit que altera o changelog seguiria uma convenção de formato, como:
  • chore(changelog): add feature for v2.2.0 by @camilamaia
  • fix(changelog): update bug fix for v2.2.0 by @joaosilva

Automação necessária:

• A automação verificaria os commits de merge no main (principalmente os commits de squash) para garantir que as alterações no changelog sejam agrupadas corretamente na pasta e no arquivo correspondente à versão.
• Quando um commit de merge for feito, a automação poderia verificar se o commit contém alterações no changelog e, se necessário, agrupar essas alterações na versão correta.
• A automação também poderia verificar a formatação dos commits para garantir que eles seguem o padrão estabelecido, garantindo a consistência e organização do changelog.

Vantagens dessa abordagem:

• Automação de merge e verificação de commits: A automação reduziria o risco de erros ao tentar combinar as mudanças feitas diretamente no repositório, garantindo que o changelog final seja consistente e sem sobreposições.
• Consistência no histórico de mudanças: Com a padronização, os commits ficam claros e facilmente rastreáveis, garantindo que o changelog final seja bem estruturado.

Desvantagens dessa abordagem:

• Dependência de padronização de commits: Todos os colaboradores precisariam seguir o padrão de commit rigorosamente, o que pode exigir algum esforço de adaptação.
• Necessidade de automação adicional: Além da padronização de commits, seria necessário configurar e manter a automação para verificar e organizar as contribuições ao changelog.

Passos

• Definir a melhor estratégia, podendo ser uma das abordagens propostas ou outra nova. Favor discutir a ideia aqui na issue antes da implementação.
• Implementar as automações necessárias.
• Testar as automações para garantir que estão funcionando corretamente.
• Garantir que o arquivo CHANGELOG.md preserve o conteúdo gerado até então, mantendo o seu padrão atual, conforme as diretrizes do Keep a Changelog. Ou seja, o resultado final deve ser o mesmo, mas o processo de geração dele deve ser adaptado.
• Atualizar as documentações de contribuição:
  • Instruções em português
  • Instruções em inglês

Links úteis

• Documentação do GitHub Actions
• Documentação sobre convenções de commit
• Keep a Changelog