gh-emillindfors-claude-marketplace-plugins-changelog/commands/changelog-add.md

description

description
Add a new entry to the CHANGELOG.md file following Keep a Changelog format

Add a new changelog entry to the project's CHANGELOG.md file. This command helps you document changes following the Keep a Changelog format (https://keepachangelog.com/).

Context

This project maintains a CHANGELOG.md file that follows the Keep a Changelog format:

• All notable changes are documented
• Format is based on Keep a Changelog
• The project adheres to Semantic Versioning
• Entries are organized by version with date stamps
• Changes are categorized as: Added, Changed, Deprecated, Removed, Fixed, Security

Task

Help the user add a well-formatted changelog entry:

1. Check for CHANGELOG.md: Look for CHANGELOG.md in the project root
2. Identify the [Unreleased] section: New entries go under the [Unreleased] section
3. Ask the user for details:
   • What type of change is this? (Added/Changed/Fixed/Removed/Security/Deprecated)
   • What is the description of the change?
   • Any additional context or details?
4. Format the entry following the Keep a Changelog format:
   • Use proper heading level (### for category)
   • Use bullet points (-)
   • Include relevant technical details
   • Reference related files, endpoints, or components
   • Be concise but descriptive
5. Add the entry under the appropriate category in the [Unreleased] section
6. Stage the file: Run git add CHANGELOG.md to stage the changes
7. Confirm: Show the user the added entry and confirm it's been staged

Keep a Changelog Categories

Added

For new features, endpoints, functionality, or capabilities.

Changed

For changes in existing functionality, including updates, enhancements, or modifications.

Deprecated

For soon-to-be removed features or functionality.

Removed

For removed features, endpoints, or functionality.

Fixed

For bug fixes, error corrections, or issue resolutions.

Security

For security improvements, vulnerability fixes, or security-related changes.

Entry Format Guidelines

Good Examples

### Added
- **System Metrics Collection**: Comprehensive system monitoring using dedicated PyIceberg table
  - Multi-Service Support: Service identification with hostname and environment
  - Comprehensive Metrics: CPU usage, memory, disk, network, and process metrics
  - Partitioned Storage: Efficiently partitioned by service_name, date, and hour

### Fixed
- **Loss Mortality Endpoint**: Fixed window function partitioning bug in `/v3/mortality/areas/month` endpoint
  - Root Cause: Window functions were using incorrect partition clause
  - Impact: Cumulative calculations now update correctly with date parameter changes
  - Solution: Updated partition clause to `PARTITION BY fdir.aquacloud_area_name`

### Changed
- **Parameter Standardization**: Migrated all v3 endpoints from `include_self` to `exclude_self` parameter
  - Updated 13 v3 SQL queries to use `$exclude_self` template parameter
  - Behavioral Consistency: Both v2 and v3 APIs now use identical parameter naming

Formatting Tips

• Use bold for main component or feature names
• Use sub-bullets for technical details, root causes, solutions, impacts
• Include file paths for code changes (e.g., services/v3/api/router.py)
• Reference endpoint paths when applicable (e.g., /v3/mortality/areas/month)
• Be specific and technical - developers will read this
• Group related changes under one main bullet when appropriate

Example Workflow

User: I fixed a bug where the API was returning 500 errors on the feeding endpoint

You: I'll help you add that to the changelog. Let me check the CHANGELOG.md file first.

[After reading the file]

Let me add this under the Fixed section in the [Unreleased] area:

### Fixed
- **Feeding Endpoint Error**: Fixed 500 server error in `/v3/feeding/sfr-by-weeknumber-and-year` endpoint
  - Root Cause: Missing AND clause in SQL WHERE statement
  - Solution: Added proper SQL syntax to fix query parsing
  - Impact: Endpoint now returns data successfully

Does this accurately describe your fix? Would you like me to add any additional details?

Important Notes

• Always add entries to the [Unreleased] section
• Don't modify versioned sections (those are historical records)
• If [Unreleased] section doesn't exist, create it at the top after the header
• Maintain consistent formatting with existing entries
• Use proper markdown syntax
• Stage the file after adding the entry so it's ready for commit
• Multiple related changes can be grouped under one main bullet point with sub-bullets

Remember: Good changelog entries help developers understand what changed, why it changed, and what impact it has.