@patricio0312rev/skillset 0.1.0

package/templates/foundation/changelog-writer/ SKILL.md

@@ -0,0 +1,431 @@
+---
+name: changelog-writer
+description: Generates changelogs and release notes from git commits, PR titles, and issue references. Organizes changes by impact type (breaking, features, fixes, improvements), formats according to Keep a Changelog standard, and provides version tagging and semantic versioning suggestions. Use when users request "create changelog", "write release notes", "document version changes", or "prepare release".
+---
+
+# Changelog & Release Notes Writer
+
+Generate professional changelogs and release notes from version control history.
+
+## Core Workflow
+
+1. **Analyze commits**: Parse git history since last release
+2. **Categorize changes**: Group by type (feat, fix, docs, etc.)
+3. **Identify breaking changes**: Flag incompatible changes
+4. **Extract highlights**: Surface most important changes
+5. **Format document**: Follow Keep a Changelog format
+6. **Suggest version**: Recommend semantic version bump
+7. **Generate release notes**: Create user-friendly summary
+
+## Commit Analysis
+
+### Extract Information From
+
+- Commit messages (preferably conventional commits)
+- PR titles and descriptions
+- Issue references (#123)
+- Merge commit messages
+- Commit authors
+
+### Parse Patterns
+
+```
+feat(auth): add OAuth2 support
+^    ^      ^
+|    |      └─ Description
+|    └─ Scope (optional)
+└─ Type
+```
+
+**Types to Categories:**
+
+- `feat` → Added
+- `fix` → Fixed
+- `docs` → Documentation
+- `style`, `refactor` → Changed
+- `perf` → Performance
+- `test` → Testing
+- `chore`, `ci` → Internal
+- `BREAKING CHANGE` → Breaking Changes
+
+## Changelog Format (Keep a Changelog)
+
+```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]
+
+### Added
+
+- New feature X
+- Support for Y
+
+### Changed
+
+- Updated Z behavior
+
+### Fixed
+
+- Resolved issue #123
+
+## [2.1.0] - 2024-01-15
+
+### Added
+
+- OAuth2 authentication support
+- User profile management API
+- Dark mode toggle
+
+### Changed
+
+- Improved error messages
+- Updated dependencies to latest versions
+
+### Deprecated
+
+- Legacy authentication method (will be removed in 3.0.0)
+
+### Fixed
+
+- Memory leak in WebSocket connection
+- Incorrect date formatting in reports
+- Race condition in concurrent requests
+
+### Security
+
+- Patched XSS vulnerability in user input
+
+## [2.0.0] - 2023-12-01
+
+### Breaking Changes
+
+- ⚠️ Removed support for Node.js 16
+- ⚠️ Changed API response format for `/users` endpoint
+- ⚠️ Renamed `config.yaml` to `config.yml`
+
+### Added
+
+- Complete API rewrite with improved performance
+- WebSocket support for real-time updates
+
+### Migration Guide
+
+See [MIGRATION_v2.md](./docs/MIGRATION_v2.md) for upgrade instructions.
+
+[unreleased]: https://github.com/user/project/compare/v2.1.0...HEAD
+[2.1.0]: https://github.com/user/project/compare/v2.0.0...v2.1.0
+[2.0.0]: https://github.com/user/project/releases/tag/v2.0.0
+```
+
+## Release Notes Format
+
+````markdown
+# Release v2.1.0 - "Feature Release Name"
+
+Released: January 15, 2024
+
+## 🎉 Highlights
+
+This release brings major improvements to authentication and user experience:
+
+- **OAuth2 Support**: Users can now sign in with Google, GitHub, and Microsoft
+- **Dark Mode**: Toggle between light and dark themes
+- **Performance**: 40% faster API response times
+
+## ✨ New Features
+
+- OAuth2 authentication with popular providers (#456)
+- User profile management API (#478)
+- Dark mode toggle in settings (#492)
+- Export data in CSV format (#501)
+
+## 🐛 Bug Fixes
+
+- Fixed memory leak in WebSocket connections (#489)
+- Resolved incorrect date formatting in reports (#495)
+- Fixed race condition in concurrent API requests (#503)
+
+## 🔄 Changes
+
+- Improved error messages across the application
+- Updated all dependencies to latest stable versions
+- Refined UI animations for smoother experience
+
+## 🔒 Security
+
+- Patched XSS vulnerability in user input validation
+- Updated JWT library to address CVE-2024-1234
+
+## 📚 Documentation
+
+- Added OAuth2 setup guide
+- Updated API reference with new endpoints
+- Improved troubleshooting section
+
+## 🙏 Contributors
+
+Thank you to all contributors who made this release possible:
+
+- @alice - OAuth2 implementation
+- @bob - Dark mode feature
+- @charlie - Bug fixes and testing
+
+## 📦 Installation
+
+```bash
+npm install project-name@2.1.0
+# or
+yarn add project-name@2.1.0
+```
+````
+
+## 🔗 Links
+
+- [Full Changelog](https://github.com/user/project/compare/v2.0.0...v2.1.0)
+- [Documentation](https://docs.projectname.com)
+- [Migration Guide](./docs/MIGRATION_v2.md)
+
+---
+
+**Note:** This is a minor release. No breaking changes. Safe to upgrade from 2.0.x.
+
+````
+
+## Semantic Versioning Rules
+
+Given a version number MAJOR.MINOR.PATCH (e.g., 2.1.0):
+
+1. **MAJOR** (2.x.x → 3.x.x)
+   - Breaking changes
+   - Incompatible API changes
+   - Removed features
+
+2. **MINOR** (2.1.x → 2.2.x)
+   - New features
+   - Backward-compatible functionality
+   - Deprecated features
+
+3. **PATCH** (2.1.0 → 2.1.1)
+   - Bug fixes
+   - Security patches
+   - Performance improvements
+
+**Special versions:**
+- `0.x.x` - Initial development (breaking changes allowed in minor)
+- `x.y.0-alpha.1` - Pre-release
+- `x.y.0-beta.2` - Beta release
+- `x.y.0-rc.1` - Release candidate
+
+## Git Commands for Changelog Generation
+
+```bash
+# Get commits since last tag
+git log $(git describe --tags --abbrev=0)..HEAD --oneline
+
+# Get commits between two tags
+git log v2.0.0..v2.1.0 --oneline
+
+# Get commits with PR numbers
+git log --merges --pretty=format:"%s" v2.0.0..HEAD
+
+# Get contributors
+git log v2.0.0..HEAD --format='%aN' | sort -u
+
+# Get commit count by type
+git log v2.0.0..HEAD --oneline | grep -E '^[a-f0-9]+ (feat|fix|docs)' | cut -d' ' -f2 | sort | uniq -c
+````
+
+## Breaking Changes Detection
+
+Look for these indicators:
+
+- Commit message contains `BREAKING CHANGE:`
+- Commit type has `!` (e.g., `feat!:`)
+- PR labeled with "breaking-change"
+- Major dependency updates
+- API endpoint changes
+- Config file format changes
+
+**Document clearly:**
+
+````markdown
+### Breaking Changes
+
+⚠️ **API Response Format Changed**
+
+The `/api/users` endpoint now returns:
+
+```json
+// Before
+{ "data": [...] }
+
+// After
+{ "users": [...], "total": 100 }
+```
+````
+
+**Migration:** Update your API client to access `users` instead of `data`.
+
+````
+
+## Automation Tools
+
+### Using conventional-changelog
+```bash
+npm install -g conventional-changelog-cli
+
+# Generate changelog
+conventional-changelog -p angular -i CHANGELOG.md -s
+
+# Generate for specific version
+conventional-changelog -p angular -i CHANGELOG.md -s -r 0
+````
+
+### Using git-cliff
+
+```bash
+# Install git-cliff
+cargo install git-cliff
+
+# Generate changelog
+git-cliff --tag v2.1.0 > CHANGELOG.md
+
+# Generate release notes
+git-cliff --tag v2.1.0 --unreleased
+```
+
+### GitHub Release Script
+
+```bash
+#!/bin/bash
+# scripts/release.sh
+
+VERSION=$1
+PREVIOUS_TAG=$(git describe --tags --abbrev=0)
+
+# Generate release notes
+gh release create "$VERSION" \
+  --title "Release $VERSION" \
+  --notes "$(git log $PREVIOUS_TAG..HEAD --pretty=format:'- %s')"
+```
+
+## User-Facing vs Developer-Facing
+
+### User-Facing (Release Notes)
+
+- Focus on benefits and features
+- Less technical jargon
+- Include screenshots/demos
+- Highlight user experience improvements
+- Provide upgrade instructions
+
+### Developer-Facing (Changelog)
+
+- Technical details
+- API changes
+- Breaking changes with migration guides
+- Dependencies updates
+- Internal refactorings
+
+## Templates by Project Type
+
+### Library/Package
+
+Focus on: API changes, breaking changes, new methods
+
+### Application
+
+Focus on: New features, bug fixes, UI improvements
+
+### CLI Tool
+
+Focus on: New commands, flag changes, behavior changes
+
+### API Service
+
+Focus on: Endpoint changes, performance, security
+
+## Best Practices
+
+1. **Be specific**: "Fixed login bug" → "Fixed session timeout on mobile"
+2. **Link issues**: Reference GitHub issues (#123)
+3. **Credit contributors**: Acknowledge work
+4. **Highlight impact**: Mark breaking changes clearly
+5. **Group logically**: By type, not chronologically
+6. **Update regularly**: With each release
+7. **Follow conventions**: Keep a Changelog format
+8. **Semantic versioning**: Use correctly
+
+## Changelog Entry Examples
+
+### Good Examples
+
+```markdown
+### Added
+
+- OAuth2 authentication support (#456) - @alice
+- Export data in CSV format with custom column selection (#501)
+
+### Fixed
+
+- Resolved memory leak in WebSocket connections affecting long-running sessions (#489)
+- Fixed race condition in concurrent API requests that caused data inconsistency (#503)
+```
+
+### Bad Examples
+
+```markdown
+### Added
+
+- Added stuff
+- New feature
+
+### Fixed
+
+- Fixed bug
+- Updates
+```
+
+## Version Suggestion Algorithm
+
+```
+If breaking changes detected:
+  MAJOR++, MINOR=0, PATCH=0
+Else if new features:
+  MINOR++, PATCH=0
+Else if only fixes:
+  PATCH++
+```
+
+## Release Checklist
+
+Before publishing release:
+
+- [ ] Review all commits since last release
+- [ ] Identify breaking changes
+- [ ] Categorize changes properly
+- [ ] Update CHANGELOG.md
+- [ ] Write release notes
+- [ ] Update version in package.json/pyproject.toml
+- [ ] Create git tag
+- [ ] Push tag to trigger CI/CD
+- [ ] Publish to package registry (npm, PyPI, etc.)
+- [ ] Create GitHub release with notes
+- [ ] Announce on relevant channels
+
+## Output Checklist
+
+Every changelog generation should provide:
+
+- [ ] Formatted CHANGELOG.md following Keep a Changelog
+- [ ] Release notes draft (user-friendly)
+- [ ] Semantic version suggestion (X.Y.Z)
+- [ ] Breaking changes clearly marked
+- [ ] Migration guide for breaking changes
+- [ ] Git tag command to run
+- [ ] Links to compare view