CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

changelog-management

Gerenciamento obrigatório de CHANGELOG e versionamento seguindo Keep a Changelog e Semantic Versioning em todos os projetos.

Quality

63%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./skills/workflow/changelog/SKILL.md
SKILL.md
Quality
Evals
Security

CHANGELOG Management

Regras obrigatórias para manter CHANGELOG em todos os projetos seguindo o padrão Keep a Changelog.


Quando Usar

Aplicar esta skill em TODOS os projetos quando:

  • Criando ou modificando qualquer arquivo
  • Fazendo commits
  • Preparando releases
  • Documentando mudanças

Regras CRÍTICAS (NÃO NEGOCIÁVEIS)

  1. CHANGELOG obrigatório em todos os projetos:

    • Todo projeto DEVE ter um arquivo CHANGELOG.md na raiz
    • Seguir rigorosamente o formato Keep a Changelog
    • Usar Semantic Versioning
  2. Agentes só podem modificar versão não lançada:

    • NUNCA modificar versões já lançadas (com tags como [1.2.0])
    • SEMPRE adicionar mudanças em [Unreleased]
    • Versões antigas só podem ser modificadas com permissão explícita do usuário
  3. Todas as mudanças devem estar no CHANGELOG:

    • SEMPRE documentar mudanças no CHANGELOG antes de commitar
    • Incluir resumos concisos mas completos
    • Categorizar corretamente: Added, Changed, Deprecated, Removed, Fixed, Security
  4. Formato obrigatório:

    # Changelog
    
    All notable changes to this project will be documented in this file.
    
    The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
    and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
    
    ## [Unreleased]
    
    ### Added
    - Nova funcionalidade X
    
    ### Changed
    - Melhoria Y
    
    ### Fixed
    - Correção Z
    
    ## [1.2.0] - 2025-12-08
    
    ### Added
    - Versão anterior...

Categorias do CHANGELOG

Added

  • Novas funcionalidades
  • Novos arquivos, módulos, scripts
  • Novas dependências
  • Novas configurações

Changed

  • Mudanças em funcionalidades existentes
  • Refatorações
  • Atualizações de dependências
  • Mudanças de comportamento

Deprecated

  • Funcionalidades que serão removidas em versões futuras
  • APIs obsoletas

Removed

  • Funcionalidades removidas
  • Arquivos deletados
  • Dependências removidas

Fixed

  • Correções de bugs
  • Correções de segurança
  • Correções de performance

Security

  • Vulnerabilidades corrigidas
  • Melhorias de segurança
  • Remoção de dados sensíveis

Workflow Obrigatório

  1. Antes de fazer mudanças:

    • Verificar se CHANGELOG.md existe
    • Se não existir, criar seguindo o template
  2. Durante as mudanças:

    • Documentar cada mudança relevante
    • Categorizar corretamente
    • Adicionar em [Unreleased]
  3. Antes de commitar:

    • Verificar se todas as mudanças estão no CHANGELOG
    • Garantir que está em [Unreleased]
    • Não modificar versões já lançadas
  4. Ao criar release:

    • Mover [Unreleased] para nova versão com data
    • Criar tag Git correspondente
    • Manter link de comparação no final
    • Atualizar número de versão em documentação
    • Criar release no GitHub (se aplicável)

Exemplo de Entrada

## [Unreleased]

### Added
- Nova skill `changelog-management` para gerenciamento obrigatório de CHANGELOG
- Script `utils/database.py` genérico para queries SQL puro (Django)

### Changed
- `.gitignore` simplificado usando pastas ao invés de listar arquivos
- `skills/README.md` atualizado para referenciar scripts genéricos

### Security
- Removidas referências a projetos de trabalho confidenciais

Checklist

  • CHANGELOG.md existe na raiz do projeto
  • Todas as mudanças documentadas em [Unreleased]
  • Categorias corretas usadas (Added/Changed/Fixed/etc)
  • Versões antigas não foram modificadas
  • Formato segue Keep a Changelog
  • Links de comparação atualizados (se aplicável)

Template Inicial

Se o projeto não tem CHANGELOG, criar com este template:

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

### Added
- Initial project setup

---

[Unreleased]: https://github.com/USER/REPO/compare/v1.0.0...HEAD

Semantic Versioning

Este projeto segue Semantic Versioning 2.0.0:

  • MAJOR (X.0.0): Mudanças incompatíveis na API
  • MINOR (x.Y.0): Novas funcionalidades compatíveis
  • PATCH (x.y.Z): Correções de bugs compatíveis

Exemplos

  • 1.0.0 → 1.1.0: Nova funcionalidade adicionada
  • 1.1.0 → 1.1.1: Bug corrigido
  • 1.1.1 → 2.0.0: Mudança que quebra compatibilidade

Releases

Criando uma Release

  1. Atualizar versão nos arquivos

    • Atualizar CHANGELOG.md (mover [Unreleased] para nova versão)
    • Atualizar número de versão em documentação (se aplicável)
  2. Commit e Tag

    git commit -m "chore: release v1.2.0"
    git tag -a v1.2.0 -m "Release version 1.2.0"
    git push origin main --tags
  3. Criar Release no GitHub (se aplicável)

    • Ir para releases do repositório
    • Clicar em "Create a new release"
    • Selecionar a tag criada
    • Adicionar título: "v1.2.0 - Nome da Release"
    • Copiar conteúdo relevante do CHANGELOG
    • Publicar release

Segurança

Proteção de Tokens

Antes de commitar, sempre verificar:

# Verificar diff antes de commitar
git diff

# Procurar por tokens
grep -r "ntn_" .
grep -r "secret_" .
grep -r "password" .

Placeholders Seguros

Use sempre placeholders em documentação:

# ✗ ERRADO - Nunca commite tokens reais
TOKEN = 'ntn_ABC123XYZ456REAL_TOKEN_HERE'

# ✓ CORRETO - Use placeholders
TOKEN = 'ntn_YOUR_NOTION_TOKEN_HERE'

Recursos

Repository

fernandezbaptiste/cursor-multiagent-system

Path

skills/workflow/changelog/SKILL.md

Last updated
First committed

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.