235 lines
7.2 KiB
Markdown
235 lines
7.2 KiB
Markdown
---
|
|
name: changelog-management
|
|
description: Maintain project documentation including CHANGELOG.md, FILETREE.md, and FAILURELOG.md. Use this skill when making code changes, adding features, fixing bugs, restructuring files/directories, or when initial solutions fail. This skill ensures consistent documentation of all changes using Keep a Changelog format with semantic versioning.
|
|
---
|
|
|
|
# Changelog and Documentation Management
|
|
|
|
## Purpose
|
|
|
|
This skill provides systematic guidance for maintaining three mandatory project documentation files: CHANGELOG.md, FILETREE.md, and FAILURELOG.md. It ensures consistent tracking of all code changes, structural modifications, and debugging attempts using industry-standard formats.
|
|
|
|
## When to Use This Skill
|
|
|
|
Trigger this skill when:
|
|
|
|
- Making any code changes, feature additions, or bug fixes
|
|
- Adding, removing, or restructuring files or directories
|
|
- Initial solutions fail and debugging is required
|
|
- Completing any development task that affects the project state
|
|
|
|
## Documentation Requirements
|
|
|
|
### CHANGELOG.md - Change Tracking
|
|
|
|
**Update CHANGELOG.md for every code modification.**
|
|
|
|
Follow [Keep a Changelog](https://keepachangelog.com/) format with semantic versioning:
|
|
|
|
- Use standard categories: Added, Changed, Deprecated, Removed, Fixed, Security
|
|
- Include date stamps (YYYY-MM-DD) and version numbers for releases
|
|
- Reference GitHub issues/PRs when applicable
|
|
- Write clear, concise descriptions of changes
|
|
- Group related changes under appropriate category headings
|
|
|
|
### FILETREE.md - Structure Documentation
|
|
|
|
**Update FILETREE.md for any structural changes.**
|
|
|
|
Maintain accurate project structure representation:
|
|
|
|
- Add entries when creating new files or directories
|
|
- Remove entries when deleting files or directories
|
|
- Update paths when restructuring
|
|
- Include brief descriptions for new directories or significant files
|
|
- Keep the tree structure accurate and readable
|
|
|
|
### FAILURELOG.md - Debugging History
|
|
|
|
**Document all failed attempts when initial solutions don't work.**
|
|
|
|
Include comprehensive debugging information:
|
|
|
|
- What was tried (approach, code, commands)
|
|
- Error messages encountered (full stack traces when relevant)
|
|
- Root cause analysis (why it failed)
|
|
- Resolution approach (what finally worked)
|
|
- Lessons learned to prevent repeating the same debugging cycles
|
|
|
|
This is essential for complex integration issues and helps maintain institutional knowledge.
|
|
|
|
## Changelog Entry Format
|
|
|
|
Use this structure for all CHANGELOG.md entries:
|
|
|
|
```markdown
|
|
## [Version] - YYYY-MM-DD
|
|
|
|
### Added
|
|
|
|
- New features or functionality
|
|
- New files, endpoints, or capabilities
|
|
- New dependencies or tools
|
|
|
|
### Changed
|
|
|
|
- Modifications to existing features
|
|
- Refactoring or improvements
|
|
- Updated dependencies or configurations
|
|
|
|
### Deprecated
|
|
|
|
- Features marked for future removal
|
|
- Old APIs or endpoints being phased out
|
|
|
|
### Removed
|
|
|
|
- Deleted features, files, or functionality
|
|
- Removed dependencies
|
|
|
|
### Fixed
|
|
|
|
- Bug fixes and error corrections
|
|
- Performance issue resolutions
|
|
- Corrected behavior
|
|
|
|
### Security
|
|
|
|
- Security patches and improvements
|
|
- Vulnerability fixes
|
|
- New security features or validations
|
|
```
|
|
|
|
### Example Entry
|
|
|
|
```markdown
|
|
## [1.2.0] - 2025-11-15
|
|
|
|
### Added
|
|
|
|
- Customer search endpoint with fuzzy matching (#123)
|
|
- Export functionality for animal records to CSV format
|
|
- Automated backup system with daily scheduling
|
|
|
|
### Changed
|
|
|
|
- Updated Prisma client to v5.7.0 for performance improvements
|
|
- Refactored authentication middleware for better error handling
|
|
|
|
### Fixed
|
|
|
|
- Resolved memory leak in file upload handler (#145)
|
|
- Fixed date formatting issues in customer reports
|
|
- Corrected phone number validation regex
|
|
|
|
### Security
|
|
|
|
- Added rate limiting to prevent API abuse
|
|
- Implemented input sanitization for search queries
|
|
```
|
|
|
|
## Version Management
|
|
|
|
Apply semantic versioning (MAJOR.MINOR.PATCH) consistently:
|
|
|
|
- **MAJOR**: Breaking API changes, incompatible updates
|
|
- **MINOR**: New features that are backward compatible
|
|
- **PATCH**: Bug fixes that are backward compatible
|
|
- Tag releases in git with version numbers (e.g., `v1.2.0`)
|
|
|
|
### Version Increment Guidelines
|
|
|
|
Increment version numbers based on change significance:
|
|
|
|
- Breaking changes → increment MAJOR (1.2.3 → 2.0.0)
|
|
- New features → increment MINOR (1.2.3 → 1.3.0)
|
|
- Bug fixes → increment PATCH (1.2.3 → 1.2.4)
|
|
|
|
## Project-Specific Considerations
|
|
|
|
### API Changes
|
|
|
|
When modifying APIs:
|
|
|
|
- Document all endpoint modifications in Changed or Added
|
|
- Include request/response schema changes
|
|
- Note deprecation timelines for removed features
|
|
- Provide migration examples for breaking changes
|
|
|
|
### Database Schema Updates
|
|
|
|
When updating database schemas:
|
|
|
|
- Document migration scripts and procedures
|
|
- Note data transformation requirements
|
|
- Include rollback procedures for critical changes
|
|
- Specify Prisma version compatibility
|
|
|
|
### Performance Improvements
|
|
|
|
When optimizing performance:
|
|
|
|
- Document changes with before/after metrics when available
|
|
- Include configuration changes that affect performance
|
|
- Note any new hardware or dependency requirements
|
|
- Quantify improvements (e.g., "Reduced load time by 40%")
|
|
|
|
### Security Updates
|
|
|
|
When addressing security:
|
|
|
|
- Use the Security category in CHANGELOG.md
|
|
- Reference CVE numbers if applicable
|
|
- Describe the vulnerability and fix without exposing exploits
|
|
- Include upgrade instructions if dependencies are updated
|
|
|
|
## Workflow Integration
|
|
|
|
### Standard Development Workflow
|
|
|
|
1. Make code changes or add features
|
|
2. Update CHANGELOG.md with appropriate category entries
|
|
3. Update FILETREE.md if files/directories were added or removed
|
|
4. Commit changes with descriptive commit message
|
|
5. Reference the changelog entry in PR description
|
|
|
|
### Debugging Workflow
|
|
|
|
1. Attempt solution and encounter failure
|
|
2. Document attempt in FAILURELOG.md immediately:
|
|
- Timestamp the entry
|
|
- Describe what was tried
|
|
- Include error messages
|
|
- Note hypothesis about cause
|
|
3. Try alternative solution
|
|
4. Update FAILURELOG.md with resolution
|
|
5. Update CHANGELOG.md with the fix
|
|
|
|
### Release Workflow
|
|
|
|
1. Review all [Unreleased] entries in CHANGELOG.md
|
|
2. Determine appropriate version number using semantic versioning
|
|
3. Replace [Unreleased] with [Version] - YYYY-MM-DD
|
|
4. Create git tag with version number
|
|
5. Update any version references in package.json or similar files
|
|
|
|
## Best Practices
|
|
|
|
- **Be specific**: Avoid vague descriptions like "Fixed bugs" or "Updated code"
|
|
- **Group related changes**: Combine related modifications under a single bullet point
|
|
- **Use present tense**: Write "Add feature" not "Added feature"
|
|
- **Include context**: Mention the affected component or file when helpful
|
|
- **Link issues**: Reference GitHub issues/PRs for traceability
|
|
- **Update immediately**: Don't batch documentation updates; maintain them with code changes
|
|
- **Review before commit**: Ensure documentation accurately reflects all changes made
|
|
|
|
## Common Pitfalls to Avoid
|
|
|
|
- Forgetting to update CHANGELOG.md for "small" changes
|
|
- Using inconsistent category names (stick to the six standard categories)
|
|
- Placing entries in wrong categories (e.g., bug fix in Added instead of Fixed)
|
|
- Missing FILETREE.md updates when adding new directories
|
|
- Skipping FAILURELOG.md documentation during difficult debugging sessions
|
|
- Using incorrect date format (must be YYYY-MM-DD)
|
|
- Incrementing version numbers incorrectly
|