zhongwei/gh-emillindfors-claude-marketplace-plugins-changelog
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-29 18:25:43 +08:00
commit 1111c916df
9 changed files with 974 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

113
commands/changelog-add.md Normal file
View File

@@ -0,0 +1,113 @@
---
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](https://keepachangelog.com/en/1.0.0/)
- The project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html)
- 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
```markdown
### 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.

135
commands/changelog-init.md Normal file
View File

@@ -0,0 +1,135 @@
---
description: Initialize a new CHANGELOG.md file following Keep a Changelog format
---
Create a new CHANGELOG.md file for the project following the Keep a Changelog format standards.
## Context
A CHANGELOG.md file is essential for tracking all notable changes to a project. It should:
- Follow the Keep a Changelog format (https://keepachangelog.com/en/1.0.0/)
- Use Semantic Versioning (https://semver.org/spec/v2.0.0.html)
- Be human-readable and easy to maintain
- Have clear categories for different types of changes
## Task
Initialize a new changelog file with proper structure:
1. **Check if CHANGELOG.md exists**: Don't overwrite an existing changelog
2. **Create the file structure**:
- Add the standard header and introduction
- Include an [Unreleased] section for upcoming changes
- Add a template version section (if the project has an initial version)
- Include links to Keep a Changelog and Semantic Versioning
3. **Ask about initial version**: Should we add an initial version entry (e.g., [1.0.0])?
4. **Customize for the project**:
- Check if there's a version number in the project (package.json, pyproject.toml, etc.)
- Include relevant context for the specific project type
5. **Create the file**: Write the CHANGELOG.md to the project root
6. **Provide guidance**: Show the user how to use the new changelog
## Standard Changelog Template
```markdown
# 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]
## [1.0.0] - YYYY-MM-DD
### Added
- Initial release
```
## Categories Explanation
Include a comment in the changelog explaining the categories:
```markdown
<!--
Categories for changelog entries:
- Added: New features, endpoints, or functionality
- Changed: Changes in existing functionality
- Deprecated: Soon-to-be removed features
- Removed: Removed features or functionality
- Fixed: Bug fixes and error corrections
- Security: Security improvements and vulnerability fixes
Each entry should be concise but descriptive, include technical details,
and reference relevant files, endpoints, or components.
-->
```
## Workflow
```
User: I need to create a changelog for this project
You: I'll help you initialize a new CHANGELOG.md file. Let me first check if one already exists.
[Check for existing CHANGELOG.md]
Great! I don't see an existing CHANGELOG.md. Let me create one for you.
[Check for version information in package files]
I found your project is using version 1.0.0 from pyproject.toml.
I'll create a CHANGELOG.md with:
- Standard Keep a Changelog header
- [Unreleased] section for upcoming changes
- [1.0.0] section for the initial release
[Create the file]
✅ Created CHANGELOG.md in the project root!
Next steps:
1. Review the initial structure
2. Add any existing changes to the [Unreleased] section
3. Use /changelog-add when you make changes to the project
4. The changelog hook will ensure you update the changelog before each commit
Would you like me to add any specific entries to get you started?
```
## Version Detection
Try to detect the current version from common files:
- `package.json` (Node.js): Check the "version" field
- `pyproject.toml` (Python): Check [tool.poetry.version] or [project] version
- `Cargo.toml` (Rust): Check [package] version
- `pom.xml` (Java/Maven): Check <version> tag
- `build.gradle` (Gradle): Check version property
- `setup.py` (Python): Check version parameter
- `__version__.py`: Check __version__ variable
## Customization Options
Ask the user if they want to:
- Include an initial version entry or just [Unreleased]
- Add any specific categories they commonly use
- Include example entries to guide future updates
- Add project-specific notes or conventions
## Important Notes
- Never overwrite an existing CHANGELOG.md without explicit confirmation
- Use the current date (YYYY-MM-DD format) for version entries
- Include helpful comments for first-time users
- Make sure the format is exactly correct (Keep a Changelog is specific about format)
- After creating, suggest adding it to git: `git add CHANGELOG.md`
## Follow-up
After creating the changelog:
1. Show the user the created file
2. Explain how to use it
3. Mention the /changelog-add command
4. Remind them about the changelog hook that will enforce updates
Remember: A good initial changelog structure sets the tone for maintaining it throughout the project's lifetime.

107
commands/changelog-view.md Normal file
View File

@@ -0,0 +1,107 @@
---
description: View recent entries from the CHANGELOG.md file
---
Display recent changelog entries from the project's CHANGELOG.md file to help understand recent changes and the changelog format.
## Context
The CHANGELOG.md file contains all notable changes to the project, organized by version and date following the Keep a Changelog format.
## Task
Help the user view and understand recent changelog entries:
1. **Locate CHANGELOG.md**: Find the CHANGELOG.md file in the project root or nearby repositories
2. **Read the file**: Load the changelog content
3. **Display recent entries**:
- Show the [Unreleased] section if it exists (this shows pending changes)
- Show the 3-5 most recent versioned releases
- Format the output in a readable way
4. **Provide context**:
- Highlight the changelog format and structure
- Point out different change categories (Added, Changed, Fixed, etc.)
- Show examples of well-formatted entries
5. **Offer next steps**:
- Suggest using /changelog-add if they need to add an entry
- Point out where new entries should be added
## Display Format
Show the changelog content in a structured way:
```markdown
# Recent Changelog Entries
## [Unreleased]
[If there are unreleased entries, show them here]
## [Version] - Date
[Show recent version entries]
---
💡 Tips:
- New entries should be added to the [Unreleased] section
- Use /changelog-add to add a new entry
- Follow the existing format and style
```
## Example Output
```
# Recent Changelog Entries from CHANGELOG.md
## [Unreleased]
### Fixed
- **Feeding Endpoint Error**: Fixed 500 server error in `/v3/feeding/sfr-by-weeknumber-and-year` endpoint
## [3.7.19] - 2025-09-26
## [3.7.18] - 2025-09-26
## [3.7.17] - 2025-09-25
### Changed
- Use sudo apt install instead of curl for just install
### Fixed
- Reintroduced the period param
---
💡 The changelog follows Keep a Changelog format (https://keepachangelog.com/)
Categories used:
- Added: New features
- Changed: Changes in existing functionality
- Fixed: Bug fixes
- Removed: Removed features
- Security: Security improvements
- Deprecated: Soon-to-be removed features
To add a new entry: /changelog-add
```
## Options
If the user specifies what they want to see, adjust the output:
- "latest version" → Show only the most recent release
- "unreleased" → Show only the [Unreleased] section
- "all" → Show the entire changelog
- "last N versions" → Show the last N versions
## Additional Features
- **Search**: If user asks to search for specific terms, grep through the changelog
- **Statistics**: Can provide counts of different types of changes
- **Format check**: Can validate that the changelog follows the expected format
- **Compare**: Can compare what's in [Unreleased] vs what's committed
## Important Notes
- Make the output readable and well-formatted
- Use appropriate markdown formatting
- Highlight important sections
- Provide helpful context about the changelog structure
- Offer actionable next steps
Remember: This command helps users understand the project's change history and learn the changelog format.