Initial commit

2025-11-29 18:01:55 +08:00
commit 60782a2f51
22 changed files with 5228 additions and 0 deletions
--- a/skills/changelog-standards.md
+++ b/skills/changelog-standards.md
@@ -0,0 +1,221 @@
+---
+title: Changelog Standards
+description: Standard changelog format based on Keep a Changelog
+tags: [changelog, versioning, documentation, standards]
+---
+
+# Changelog Standards
+
+## Metadata
+
+**Purpose**: Define Standard changelog format and structure
+**Version**: 1.0.0
+
+---
+
+## Format Specification
+
+Based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) with Personal extensions.
+
+## File Locations
+
+**Flexible locations** - Teams can choose where to store changelogs:
+- `CHANGELOG.md` (project root) - Most common
+- `docs/CHANGELOG.md` - Documentation directory
+- `docs/changelog/YYYY.md` - Yearly split format for long-lived projects
+- Custom paths supported via `--path` parameter
+
+**Auto-detection order**:
+1. `CHANGELOG.md` (root)
+2. `docs/CHANGELOG.md`
+3. `docs/changelog/YYYY.md` (current year)
+4. Search for `**/CHANGELOG.md` or `**/changelog/*.md`
+
+## Version Heading Format
+
+### Semantic Versioning (SemVer)
+```markdown
+## [2.9.0] - 2024-03-15 [MVP]
+```
+
+### Calendar Versioning (CalVer)
+```markdown
+## [2025.1] - 2025-01-15 [Prototype]
+```
+
+**Components**:
+- Version in brackets: `[X.Y.Z]` or `[YYYY.N]`
+- ISO date: `YYYY-MM-DD`
+- Tier annotation (optional): `[Prototype]`, `[MVP]`, or `[Production]`
+
+## Changelog Styles
+
+### Standard Style (Default)
+
+Uses Keep a Changelog sections in this order:
+
+1. **Added** - New features
+2. **Changed** - Changes to existing functionality
+3. **Deprecated** - Soon-to-be-removed features
+4. **Removed** - Removed features
+5. **Fixed** - Bug fixes
+6. **Security** - Security fixes
+
+**Example**:
+```markdown
+### Added
+- New data validation pipeline for customer segments (#142)
+- Support for weekly aggregation in metrics (#156)
+
+### Fixed
+- Corrected timezone handling in datetime conversion (#158)
+```
+
+### Detailed Style
+
+Uses Highlights + Technical Details format for comprehensive release notes:
+
+**Structure**:
+```markdown
+## [VERSION] - YYYY-MM-DD [TIER]
+
+### Highlights
+
+Brief executive summary (2-4 key points):
+- Major feature or capability added
+- Significant improvements or changes
+- Critical fixes or updates
+
+### Detailed Notes
+
+#### Added
+- Feature description with technical details (#PR-number)
+
+#### Changed
+- Change description with rationale (#PR-number)
+
+#### Fixed
+- Bug fix with context (#PR-number)
+```
+
+**Example**:
+```markdown
+## [2.1.0] - 2025-11-15 [MVP]
+
+### Highlights
+
+- Introduced automated changelog generation from git history
+- Enhanced documentation workflow with standards validation
+- Improved token efficiency through command optimization
+
+### Detailed Notes
+
+#### Added
+- Changelog standardization capability with SemVer and CalVer support (#12)
+  - Generate new CHANGELOG.md from git history
+  - Update existing changelogs with recent commits
+  - Validate format against standards
+- Custom path support for flexible changelog locations (#12)
+
+#### Changed
+- Optimized git-workflow commands for token efficiency (#23)
+- Refactored validation logic to reduce redundancy (#23)
+
+#### Fixed
+- Corrected file size validation in pre-commit checks (#23)
+```
+
+## Unreleased Section
+
+Always include at top of changelog:
+```markdown
+## [Unreleased]
+
+### Added
+- Feature in development
+
+### Changed
+- Work in progress
+```
+
+## Complete Example
+
+```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/).
+
+## [Unreleased]
+
+### Added
+- Experimental feature X
+
+## [2.1.0] - 2025-11-01 [MVP]
+
+### Added
+- Customer segmentation model v2
+- Automated retraining pipeline
+
+### Changed
+- Updated evaluation metrics to include precision-recall curves
+
+### Fixed
+- Memory leak in batch processing
+
+## [2.0.0] - 2025-09-15 [MVP]
+
+### Added
+- Initial MVP release
+- Core recommendation engine
+- Integration with production data warehouse
+
+### Changed
+- Migrated from prototype to production-ready architecture
+
+[2.1.0]: https://github.com/org/repo/compare/v2.0.0...v2.1.0
+[2.0.0]: https://github.com/org/repo/releases/tag/v2.0.0
+```
+
+## Version Comparison Links
+
+At bottom of changelog, include links:
+```markdown
+[2.1.0]: https://github.com/org/repo/compare/v2.0.0...v2.1.0
+[2.0.0]: https://github.com/org/repo/compare/v1.0.0...v2.0.0
+[1.0.0]: https://github.com/org/repo/releases/tag/v1.0.0
+```
+
+## Tier Annotations
+
+Map project maturity to versions:
+
+- **[Prototype]** - Experimental, research phase
+- **[MVP]** - Pilot, initial production deployment
+- **[Production]** - Stable, fully supported release
+
+## Writing Guidelines
+
+**Good entries**:
+- Clear, concise descriptions
+- User-facing changes (what, not how)
+- Business impact when relevant
+- Link to issues/PRs for details
+
+**Bad entries**:
+- Implementation details
+- Commit messages verbatim
+- Internal refactoring (unless user-visible)
+
+**Example Good Entry**:
+```markdown
+### Added
+- Support for multi-year trend analysis in dashboard (#142)
+```
+
+**Example Bad Entry**:
+```markdown
+### Changed
+- Refactored utils.py to use dataclasses instead of dicts
+```