Skip to content

Guia de Manutenção do CHANGELOG.md

Introdução

Este guia destina-se a todos os desenvolvedores que contribuem para um projeto no modelo "platform" (distribuído por vários repositórios). O objetivo é garantir que as mudanças em cada módulo sejam documentadas de forma clara e concisa no CHANGELOG.md de cada repositório e no CHANGELOG.md central localizado na pasta ./k8s/ do repositório main.

Por que manter um CHANGELOG?

Um CHANGELOG.md é um arquivo que contém uma lista cronológica de todas as alterações significativas feitas no projeto para cada versão. Isso inclui novas funcionalidades, correções de bugs, e melhorias de performance ou código. Manter este arquivo ajuda não só os desenvolvedores a acompanhar as mudanças, mas também os usuários e stakeholders a entender o que foi alterado e quais são os benefícios dessas mudanças.

Estrutura do CHANGELOG

O arquivo CHANGELOG.md deve seguir o Versionamento Semântico (MAJOR.MINOR.PATCH), onde:

  • MAJOR versão quando você faz mudanças incompatíveis na API,
  • MINOR versão quando você adiciona funcionalidades de uma maneira compatível com versões anteriores, e
  • PATCH versão quando você faz correções de bugs compatíveis com versões anteriores.

Cada entrada no CHANGELOG deve conter:

  • A versão do projeto.
  • A data de lançamento no formato AAAA-MM-DD.
  • Uma lista de mudanças, classificadas por tipo: Added para novas funcionalidades, Changed para mudanças em funcionalidades existentes, Deprecated para funcionalidades que serão removidas em breve, Removed para funcionalidades removidas, Fixed para qualquer correção de bugs, e Security em caso de correções de vulnerabilidades.

Manutenção do CHANGELOG

Para Desenvolvedores

  1. Documentando mudanças locais: Para cada alteração significativa que você fizer em um módulo, adicione uma entrada no CHANGELOG.md localizado no diretório do módulo. Use o formato mencionado acima para registrar sua mudança.

  2. Detalhes são importantes: Seja específico. Mencione como a mudança afeta o projeto, por que ela é necessária, e como ela se encaixa no contexto maior do projeto.

  3. Referências: Quando possível, inclua a referência à issue do GitLab que sua mudança está endereçando (exemplo: Closes #123).

Para Mantenedores do Projeto

  1. Revisão e Consolidação: Antes de uma nova versão do projeto como um todo ser lançada, revise os CHANGELOG.md de cada módulo e consolide as informações relevantes no CHANGELOG.md localizado na pasta ./k8s/.

  2. Foco no Usuário: No CHANGELOG.md central, concentre-se em descrever as funcionalidades e mudanças de uma perspectiva de usuário, destacando melhorias, correções e novas funcionalidades que agreguem valor ao projeto.

  3. Atualização Pré-Lançamento: Sempre atualize o CHANGELOG.md central antes de um lançamento, garantindo que todas as alterações dos módulos estejam refletidas.

Exemplo de Entrada no CHANGELOG

## [1.1.0] - 2023-11-03

### Added
- Função de login via biometria no módulo Client Front (Closes #42).

### Changed
- Atualização do Helm Chart para suportar a nova estrutura de containers.

## [1.0.1] - 2023-11-01

### Fixed
- Correção da vulnerabilidade de segurança no SAS Token Middleware.

### Security
- Atualizações de dependências críticas para o Core Django.

Evite misturar correções de bugs e novas funcionalidades em uma única entrada. Isso pode dificultar a compreensão das mudanças por parte dos usuários finais e atrapalha as contagens e emissão de faturas ao cliente. Em vez disso, separe as mudanças em entradas separadas, classificadas por tipo.

Conclusão

O CHANGELOG.md é um documento vital para o projeto e deve ser mantido com a mesma seriedade que o código-fonte. Cumprir com este guia ajudará a equipe a manter um histórico consistente e útil, que beneficia tanto os desenvolvedores quanto os usuários finais.

Práticas Recomendadas

  • Consistência: Use uma linguagem e um formato consistentes em todas as entradas do CHANGELOG. Evite usar abreviações ou jargões que possam ser confusos para os usuários finais.
  • Automatização: Considere usar ferramentas para automatizar o processo de geração do changelog com base em mensagens de commit, tags e merge requests.
  • Revisão Cruzada: Encoraje a revisão cruzada de entradas no changelog por outros desenvolvedores para minimizar erros e omissões.
  • Comunicação: Certifique-se de que todos os membros da equipe entendam a importância de manter o CHANGELOG e saibam como fazer isso corretamente.

Ferramentas e Recursos

Algumas ferramentas que podem ajudar na manutenção do CHANGELOG:

  • git-chglog: Uma ferramenta para gerar CHANGELOG.md a partir de tags e mensagens de commit do Git.
  • standard-version: Uma ferramenta para versionamento semântico, que automatiza o processo de versionamento e geração de changelog.
  • Keep a Changelog: Um site que fornece mais orientações sobre como manter um CHANGELOG.

Conclusão

Manter um CHANGELOG.md detalhado e bem organizado é uma parte essencial do gerenciamento de projetos de software. Isso não apenas melhora a comunicação dentro da equipe, mas também ajuda a construir confiança com os usuários finais, que podem facilmente acompanhar o progresso e entender as mudanças implementadas.

Certifique-se de atualizar este guia conforme necessário para refletir as melhores práticas e quaisquer novas ferramentas ou processos adotados pela equipe.

Boas práticas de codificação e documentação!

Diferenças entre o CHANGELOG de um Módulo e o CHANGELOG na pasta k8s

Introdução

No ecossistema de um projeto "platform", a documentação de mudanças é mantida tanto em nível de módulo quanto no nível do projeto. Este documento esclarece a distinção entre o CHANGELOG.md de um módulo individual e o CHANGELOG.md localizado na pasta ./k8s/ do repositório principal.

CHANGELOG de um Módulo

Definição

O CHANGELOG.md de um módulo é um arquivo dedicado a documentar as mudanças, melhorias, correções de bugs e atualizações que são aplicadas especificamente àquele módulo.

Propósito

  • Foco no Desenvolvimento: Acompanhar o progresso técnico e as alterações detalhadas do módulo em particular.
  • Histórico de Versões: Registrar cada versão incremental do módulo com base em correções, melhorias e novas funcionalidades.
  • Documentação para Desenvolvedores: Servir como uma referência imediata para desenvolvedores que trabalham ou dependem do módulo.

Conteúdo

  • Detalhes técnicos específicos das mudanças.
  • Referências a commits, pull requests ou issues específicas do módulo.
  • Versões semânticas (MAJOR.MINOR.PATCH) aplicadas ao contexto do módulo.

CHANGELOG na pasta k8s

Definição

O CHANGELOG.md localizado na pasta ./k8s/ do repositório principal (Main) é o arquivo que captura uma visão de alto nível das mudanças em toda a plataforma Sebralab-platform.

Propósito

  • Visão do Projeto: Oferecer uma visão geral das funcionalidades implementadas, melhorias e correções em todo o projeto.
  • Coordenação de Releases: Documentar a integração dos diferentes módulos e como eles funcionam juntos em uma determinada versão do projeto.
  • Foco no Usuário e Deploy: Destacar mudanças que afetam a implementação e o uso do projeto como um todo, incluindo atualizações no Helm Chart e na infraestrutura de Kubernetes.

Conteúdo

  • Sumário das alterações nos módulos que têm um impacto direto no funcionamento integrado da plataforma.
  • Informações sobre atualizações de dependências e configurações de infraestrutura.
  • Versões semânticas representando lançamentos significativos do projeto total, não apenas de um módulo isolado.

Principais Diferenças

  • Granularidade: O CHANGELOG.md de um módulo é detalhado e técnico, enquanto o CHANGELOG.md na pasta k8s é mais generalista e focado em como as partes se integram.
  • Público-Alvo: O público do changelog do módulo são principalmente desenvolvedores, enquanto o da pasta k8s inclui gestores de projeto, operadores de DevOps e stakeholders.
  • Frequência de Atualização: O changelog do módulo é atualizado frequentemente com cada subversão, já o da pasta k8s é atualizado em marcos mais significativos do projeto.
  • Escopo de Conteúdo: O changelog do módulo cobre mudanças específicas daquele componente, enquanto o da pasta k8s abrange mudanças que impactam a operacionalização e entrega do projeto completo.

Conclusão

Entender a distinção entre o CHANGELOG.md de um módulo e o CHANGELOG.md da pasta k8s é crucial para a documentação efetiva e comunicação clara dentro da equipe do projeto Sebralab-platform. Cada um tem um papel vital na gestão do projeto e na entrega de informações relevantes aos seus respectivos públicos.

Mantenha ambos os arquivos atualizados e consistentes com as práticas documentadas para garantir que todas as partes interessadas estejam informadas e alinhadas com o desenvolvimento do projeto.