Initial commit
This commit is contained in:
Zhongwei Li
194
skills/adr-authoring.md
Normal file
194
skills/adr-authoring.md
Normal file
@@ -0,0 +1,194 @@
|
||||
---
|
||||
title: ADR Authoring
|
||||
description: MADR format structure and best practices for Architecture Decision Records
|
||||
tags: [adr, documentation, decisions, madr]
|
||||
---
|
||||
|
||||
# ADR Authoring
|
||||
|
||||
## Metadata
|
||||
|
||||
**Purpose**: Provide MADR template structure and ADR best practices
|
||||
**Version**: 1.0.0
|
||||
|
||||
---
|
||||
|
||||
## ADR Template
|
||||
|
||||
```markdown
|
||||
# ADR-XXX: [Short Decision Title]
|
||||
|
||||
**Status:** [Proposed/Accepted/Superseded/Rejected]
|
||||
**Date:** YYYY-MM-DD
|
||||
**Deciders:** [Names or roles]
|
||||
**Maturity Level:** [Experimental/Prototype/Production]
|
||||
**Handoff Impact:** [None/Low/Medium/High]
|
||||
|
||||
## Context
|
||||
|
||||
[What is the issue we're addressing? What stage of the project are we in?
|
||||
What business problem or research question drives this decision?]
|
||||
|
||||
## Decision Drivers
|
||||
|
||||
- [Driver 1: e.g., Must achieve 95% accuracy for business case]
|
||||
- [Driver 2: e.g., Inference latency must be <100ms]
|
||||
- [Driver 3: e.g., Solution must be interpretable for business users]
|
||||
- [Driver 4: e.g., Limited to X budget/compute resources]
|
||||
|
||||
## Options Considered
|
||||
|
||||
### Option 1: [Name]
|
||||
**Description:** [Brief explanation]
|
||||
|
||||
**Pros:**
|
||||
- [Advantage 1]
|
||||
- [Advantage 2]
|
||||
|
||||
**Cons:**
|
||||
- [Disadvantage 1]
|
||||
- [Disadvantage 2]
|
||||
|
||||
**Evaluation Results:** [Benchmark numbers, if applicable]
|
||||
|
||||
### Option 2: [Name] ⭐ SELECTED
|
||||
**Description:** [Brief explanation]
|
||||
|
||||
**Pros:**
|
||||
- [Advantage 1]
|
||||
- [Advantage 2]
|
||||
|
||||
**Cons:**
|
||||
- [Disadvantage 1]
|
||||
- [Disadvantage 2]
|
||||
|
||||
**Evaluation Results:** [Benchmark numbers, if applicable]
|
||||
|
||||
## Decision
|
||||
|
||||
We will [clear, active voice statement of what we're doing].
|
||||
|
||||
[For production decisions] This will be handed off to [team name] with the following support: [describe transition plan].
|
||||
|
||||
## Consequences
|
||||
|
||||
### Positive Outcomes
|
||||
- [What becomes easier or better]
|
||||
- [Capabilities we gain]
|
||||
|
||||
### Negative Outcomes
|
||||
- [What becomes harder]
|
||||
- [Capabilities we sacrifice]
|
||||
|
||||
### Risks & Mitigation
|
||||
- **Risk:** [Potential problem]
|
||||
**Mitigation:** [How we'll address it]
|
||||
|
||||
### Implications for Business Team *(if applicable)*
|
||||
- **What they need to know:** [Critical context for maintenance]
|
||||
- **What they can modify:** [Safe changes they can make independently]
|
||||
- **What requires re-engagement:** [Changes that need our team's input]
|
||||
- **Required expertise:** [Skills needed to maintain this]
|
||||
|
||||
## Related ADRs
|
||||
|
||||
- Supersedes: [ADR-XXX if replacing an older decision]
|
||||
- Related to: [ADR-YYY if connected to other decisions]
|
||||
- Informed by: [ADR-ZZZ if building on previous work]
|
||||
|
||||
## References
|
||||
|
||||
[Links to detailed documentation, code, experiments, papers, etc.]
|
||||
```
|
||||
|
||||
## Naming and Numbering
|
||||
|
||||
**Filename format**: `XXX-title-in-kebab-case.md`
|
||||
**Sequential numbering**: 001, 002, 003, etc.
|
||||
**Storage location**: `adr/` directory (Personal standard)
|
||||
|
||||
**IMPORTANT**:
|
||||
- All ADRs MUST be stored in `adr/` directory
|
||||
- If the `adr/` directory does not exist, create it first: `mkdir -p adr`
|
||||
- Do NOT store ADRs in `docs/adr/` or any other location
|
||||
|
||||
## Maturity Levels
|
||||
|
||||
**Experimental** (Tier 1):
|
||||
- Algorithm selection, feature engineering, evaluation metrics
|
||||
- Review: Author + 1 peer (1-2 days)
|
||||
|
||||
**Prototype** (Tier 2):
|
||||
- Infrastructure choices, in-market test design, data pipelines
|
||||
- Review: Author + technical lead + 1 developer (3-5 days)
|
||||
|
||||
**Production** (Tier 3):
|
||||
- Production architecture, monitoring, retraining strategies
|
||||
- Review: Author + technical lead + business rep (5-7 days with meeting)
|
||||
|
||||
## Handoff Impact Levels
|
||||
|
||||
- **None**: Internal research decision, no handoff
|
||||
- **Low**: Minor impact on business team maintenance
|
||||
- **Medium**: Requires business team understanding
|
||||
- **High**: Critical for business team success, requires training
|
||||
|
||||
## Status Lifecycle
|
||||
|
||||
1. **Proposed** - Under review, not yet accepted
|
||||
2. **Accepted** - Approved and active
|
||||
3. **Rejected** - Considered but not chosen
|
||||
4. **Superseded** - Replaced by a newer ADR (reference the new ADR number)
|
||||
|
||||
## Best Practices
|
||||
|
||||
**Title**:
|
||||
- Describes the decision, not the problem
|
||||
- Noun phrase (e.g., "Use of PostgreSQL for feature store")
|
||||
|
||||
**Context**:
|
||||
- What problem are we solving?
|
||||
- What constraints exist?
|
||||
- Why does this matter?
|
||||
|
||||
**Decision Drivers**:
|
||||
- List 3-5 key factors influencing the decision
|
||||
- Be specific (e.g., "Team has PostgreSQL expertise")
|
||||
|
||||
**Considered Options**:
|
||||
- Always include at least 2-3 alternatives
|
||||
- Show you explored options
|
||||
|
||||
**Consequences**:
|
||||
- Be honest about trade-offs
|
||||
- List both positive and negative impacts
|
||||
- Include neutral consequences too
|
||||
|
||||
**Links**:
|
||||
- Reference related ADRs
|
||||
- Link to external documentation
|
||||
- Show decision relationships
|
||||
|
||||
## When to Write ADRs
|
||||
|
||||
**Always write for**:
|
||||
- Core methodology choices (algorithms, model architecture)
|
||||
- Data architecture (storage, pipelines, schemas)
|
||||
- Infrastructure decisions (cloud, framework, deployment)
|
||||
- Evaluation approach changes
|
||||
- Decisions persisting to production
|
||||
- Significant pivots
|
||||
- Failed experiments (status: Rejected)
|
||||
|
||||
**Use judgment for**:
|
||||
- Temporary workarounds (if marked non-permanent)
|
||||
- Tool choices for exploration (if not affecting deliverables)
|
||||
- Hyperparameter decisions (unless novel or critical)
|
||||
|
||||
**Don't write for**:
|
||||
- Individual experiment runs
|
||||
- Personal workflow preferences
|
||||
- Notebook organization
|
||||
- Obvious/trivial choices
|
||||
|
||||
**Rule of thumb**: If someone might ask "why did we do it this way?" 6 months from now, write an ADR.
|
||||
221
skills/changelog-standards.md
Normal file
221
skills/changelog-standards.md
Normal file
@@ -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
|
||||
```
|
||||
97
skills/diagram-analysis.md
Normal file
97
skills/diagram-analysis.md
Normal file
@@ -0,0 +1,97 @@
|
||||
---
|
||||
title: Diagram Analysis
|
||||
description: Understanding system architecture to choose appropriate diagram types
|
||||
tags: [analysis, diagrams, architecture, visualization]
|
||||
---
|
||||
|
||||
# Diagram Analysis
|
||||
|
||||
## Metadata
|
||||
|
||||
**Purpose**: Analyze systems to determine best diagram type and content
|
||||
**Version**: 1.0.0
|
||||
|
||||
---
|
||||
|
||||
## Analysis Steps
|
||||
|
||||
### 1. Understand the Goal
|
||||
|
||||
**Ask**:
|
||||
- What story needs to be told?
|
||||
- Who is the audience?
|
||||
- What decisions will this support?
|
||||
- What level of detail is needed?
|
||||
|
||||
### 2. Identify Architecture Type
|
||||
|
||||
**Common patterns**:
|
||||
- **Monolithic** - Single application, internal modules
|
||||
- **Microservices** - Multiple services, APIs, message queues
|
||||
- **Data pipeline** - Data flow from sources to outputs
|
||||
- **ML system** - Training vs inference pipelines
|
||||
- **Library/Framework** - Class hierarchies, modules
|
||||
|
||||
### 3. Choose Diagram Type
|
||||
|
||||
**For system overview**: C4 Context
|
||||
**For service architecture**: C4 Container or Flowchart
|
||||
**For internal structure**: C4 Component or Class Diagram
|
||||
**For interactions**: Sequence Diagram
|
||||
**For data models**: ER Diagram
|
||||
**For processes**: Flowchart
|
||||
**For state changes**: State Diagram
|
||||
|
||||
### 4. Determine Scope
|
||||
|
||||
**Include**:
|
||||
- Essential components for the story
|
||||
- Key relationships and dependencies
|
||||
- Technology choices (if relevant to audience)
|
||||
|
||||
**Exclude**:
|
||||
- Implementation details (unless that's the focus)
|
||||
- Everything not needed for this specific diagram
|
||||
- Redundant information
|
||||
|
||||
## Discovery Commands
|
||||
|
||||
**System boundaries**:
|
||||
```bash
|
||||
# Find services/modules
|
||||
ls -d */ | head -10
|
||||
find . -name "docker-compose.yml" -o -name "Dockerfile"
|
||||
```
|
||||
|
||||
**Interactions**:
|
||||
```bash
|
||||
# Find API definitions
|
||||
find . -name "*api*.py" -o -name "*route*.py"
|
||||
|
||||
# Check for message queues
|
||||
grep -r "kafka\|rabbitmq\|redis\|celery" pyproject.toml requirements.txt
|
||||
```
|
||||
|
||||
**Data flow**:
|
||||
```bash
|
||||
# Find data sources
|
||||
find . -name "*data*" -o -name "*extract*" -o -name "*load*"
|
||||
|
||||
# Check databases
|
||||
grep -i "postgres\|mysql\|mongo\|sqlite" pyproject.toml requirements.txt
|
||||
```
|
||||
|
||||
## Diagram Planning
|
||||
|
||||
**Start simple**:
|
||||
1. List main components
|
||||
2. Identify key relationships
|
||||
3. Choose direction (TD/LR)
|
||||
4. Add labels
|
||||
5. Refine as needed
|
||||
|
||||
**Validate**:
|
||||
- Does it tell the right story?
|
||||
- Is it too complex?
|
||||
- Is anything missing?
|
||||
- Will the audience understand it?
|
||||
265
skills/git-history-analysis.md
Normal file
265
skills/git-history-analysis.md
Normal file
@@ -0,0 +1,265 @@
|
||||
---
|
||||
title: Git History Analysis
|
||||
description: Patterns for parsing git commits and PRs to infer changelog entries
|
||||
tags: [git, commits, changelog, parsing]
|
||||
---
|
||||
|
||||
# Git History Analysis
|
||||
|
||||
## Metadata
|
||||
|
||||
**Purpose**: Extract changelog entries from git history
|
||||
**Version**: 1.0.0
|
||||
|
||||
---
|
||||
|
||||
## Git Log Commands
|
||||
|
||||
### Retrieve Commits in Range
|
||||
|
||||
**All commits since last tag**:
|
||||
```bash
|
||||
git log $(git describe --tags --abbrev=0)..HEAD --pretty=format:"%h|%s|%an|%ad" --date=short
|
||||
```
|
||||
|
||||
**All commits since specific date**:
|
||||
```bash
|
||||
git log --since="2025-01-01" --pretty=format:"%h|%s|%an|%ad" --date=short
|
||||
```
|
||||
|
||||
**All commits between two refs**:
|
||||
```bash
|
||||
git log v1.0.0..v2.0.0 --pretty=format:"%h|%s|%an|%ad" --date=short
|
||||
```
|
||||
|
||||
**Format explained**:
|
||||
- `%h` - Short commit hash
|
||||
- `%s` - Subject/title
|
||||
- `%an` - Author name
|
||||
- `%ad` - Author date
|
||||
- `|` - Delimiter for parsing
|
||||
|
||||
### Exclude Noise Commits
|
||||
|
||||
**Filter out merge commits**:
|
||||
```bash
|
||||
git log --no-merges
|
||||
```
|
||||
|
||||
**Filter out version bump commits**:
|
||||
```bash
|
||||
git log --grep="^Bump version" --invert-grep
|
||||
```
|
||||
|
||||
**Combined filters**:
|
||||
```bash
|
||||
git log --no-merges --grep="^Bump version\|^Release" --invert-grep
|
||||
```
|
||||
|
||||
## Commit Message Parsing
|
||||
|
||||
### Conventional Commits
|
||||
|
||||
**Format**: `<type>(<scope>): <description>`
|
||||
|
||||
See "Changelog Section Mapping" table below for complete type-to-section mappings.
|
||||
|
||||
**Examples**:
|
||||
```
|
||||
feat(api): add customer export endpoint → Added
|
||||
fix(auth): resolve timeout on login → Fixed
|
||||
perf(db): optimize query performance → Changed
|
||||
security(deps): update vulnerable packages → Security
|
||||
```
|
||||
|
||||
**Parsing regex**: `^(feat|fix|docs|refactor|perf|test|chore|security)(\([^\)]+\))?: (.+)$`
|
||||
|
||||
### Non-Conventional Commits
|
||||
|
||||
**Keyword-based categorization**:
|
||||
|
||||
**Added indicators**:
|
||||
- Starts with: "Add", "Implement", "Introduce", "Create"
|
||||
- Contains: "new feature", "support for"
|
||||
|
||||
**Fixed indicators**:
|
||||
- Starts with: "Fix", "Resolve", "Correct", "Patch"
|
||||
- Contains: "bug", "issue", "error", "crash"
|
||||
|
||||
**Changed indicators**:
|
||||
- Starts with: "Update", "Improve", "Enhance", "Optimize", "Refactor"
|
||||
- Contains: "performance", "efficiency"
|
||||
|
||||
**Removed indicators**:
|
||||
- Starts with: "Remove", "Delete", "Drop"
|
||||
- Contains: "deprecated", "legacy"
|
||||
|
||||
**Security indicators**:
|
||||
- Contains: "security", "vulnerability", "CVE-", "XSS", "injection"
|
||||
|
||||
**Example classification**:
|
||||
```
|
||||
"Add customer segmentation feature" → Added
|
||||
"Fix memory leak in batch processing" → Fixed
|
||||
"Update data validation logic" → Changed
|
||||
"Remove deprecated API endpoints" → Removed
|
||||
"Patch security vulnerability in auth" → Security
|
||||
```
|
||||
|
||||
## PR Title Parsing
|
||||
|
||||
GitHub/GitLab PR titles often follow similar patterns:
|
||||
|
||||
**PR number extraction**:
|
||||
```bash
|
||||
gh pr list --state merged --limit 100 --json number,title,mergedAt
|
||||
```
|
||||
|
||||
**Parse PR titles** using same rules as commit messages
|
||||
|
||||
**Prefer PR titles over commits** when available (cleaner, more user-facing)
|
||||
|
||||
## Extracting PR/Issue References
|
||||
|
||||
**From commit messages**:
|
||||
- Pattern 1: `(#123)` at end of message
|
||||
- Pattern 2: `#123` anywhere in message
|
||||
- Pattern 3: `Merge pull request #123`
|
||||
- Pattern 4: `Fixes #123`, `Closes #123`, `Resolves #123`
|
||||
|
||||
**From PR list**:
|
||||
```bash
|
||||
# Get PR number associated with commit
|
||||
gh pr list --state merged --search "sha:COMMIT_HASH" --json number
|
||||
```
|
||||
|
||||
**Link format in changelog**:
|
||||
- Short form: `(#123)` for PR/issue number
|
||||
- Full entries: `- Feature description (#123)`
|
||||
- Multi-ref: `- Feature description (#123, #124)`
|
||||
|
||||
## Filtering Strategy
|
||||
|
||||
### Skip These Commits
|
||||
|
||||
**Merge commits**:
|
||||
- Pattern: `^Merge (branch|pull request)`
|
||||
|
||||
**Version bumps**:
|
||||
- Pattern: `^(Bump|Release|Version) (version )?[0-9]`
|
||||
|
||||
**Internal housekeeping**:
|
||||
- Pattern: `^(chore|ci|test|docs):`
|
||||
- Exception: Major docs overhauls might be "Added"
|
||||
|
||||
**WIP commits**:
|
||||
- Pattern: `^WIP:`, `^temp:`, `^tmp:`
|
||||
|
||||
### Grouping and Deduplication
|
||||
|
||||
**Group by scope** (if using conventional commits):
|
||||
```
|
||||
feat(api): add export endpoint
|
||||
feat(api): add import endpoint
|
||||
→ Group under "API" subsection in Added
|
||||
```
|
||||
|
||||
**Deduplicate similar commits**:
|
||||
```
|
||||
fix: typo in validation message
|
||||
fix: another typo in error message
|
||||
→ Combine as "Fixed typos in validation messages"
|
||||
```
|
||||
|
||||
**Squash implementation details**:
|
||||
```
|
||||
feat: add customer export (part 1)
|
||||
feat: add customer export (part 2)
|
||||
feat: finalize customer export
|
||||
→ Single entry: "Customer export feature"
|
||||
```
|
||||
|
||||
## Changelog Section Mapping
|
||||
|
||||
**Type → Section mapping**:
|
||||
|
||||
| Commit Type | Changelog Section | Notes |
|
||||
|-------------|-------------------|-------|
|
||||
| `feat` | Added | New features |
|
||||
| `fix` | Fixed | Bug fixes |
|
||||
| `perf` | Changed | Performance improvements |
|
||||
| `refactor` | Changed | Only if user-facing |
|
||||
| `security` | Security | Security patches |
|
||||
| `deprecate` | Deprecated | Features marked for removal |
|
||||
| `remove` | Removed | Deleted features |
|
||||
| `docs` | (Skip) | Unless major docs addition |
|
||||
| `test` | (Skip) | Internal only |
|
||||
| `chore` | (Skip) | Internal only |
|
||||
| `ci` | (Skip) | Internal only |
|
||||
|
||||
## Extracting User-Facing Changes
|
||||
|
||||
**Focus on impact, not implementation**:
|
||||
|
||||
**Good**: "Added support for multi-year trend analysis"
|
||||
**Bad**: "Refactored TrendAnalyzer class to support configurable date ranges"
|
||||
|
||||
**Transformation examples**:
|
||||
|
||||
```
|
||||
Git: "refactor: extract validation logic to separate module"
|
||||
→ Skip (internal refactoring)
|
||||
|
||||
Git: "feat: implement caching layer for API responses"
|
||||
→ Added: "API response caching for improved performance"
|
||||
|
||||
Git: "fix: handle edge case in date parsing"
|
||||
→ Fixed: "Corrected date parsing for edge cases"
|
||||
|
||||
Git: "perf(db): add indexes to customer table"
|
||||
→ Changed: "Improved database query performance"
|
||||
```
|
||||
|
||||
## Git Commands Summary
|
||||
|
||||
**Get commits since last version**:
|
||||
```bash
|
||||
git log $(git describe --tags --abbrev=0)..HEAD --no-merges --pretty=format:"%h|%s"
|
||||
```
|
||||
|
||||
**Get all tags** (for version detection):
|
||||
```bash
|
||||
git tag --list --sort=-version:refname
|
||||
```
|
||||
|
||||
**Get commit count** (for version increment hint):
|
||||
```bash
|
||||
git rev-list --count $(git describe --tags --abbrev=0)..HEAD
|
||||
```
|
||||
|
||||
**Check if commit is a merge**:
|
||||
```bash
|
||||
git rev-list --parents -n 1 <commit-hash> | grep -q " .* .*"
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Prefer PR titles** over individual commits when available
|
||||
2. **Group related changes** by feature or component
|
||||
3. **Use user-facing language**, avoid technical jargon
|
||||
4. **Skip internal commits** that don't affect users
|
||||
5. **Combine granular commits** into cohesive changelog entries
|
||||
6. **Link to issues/PRs** for detailed context
|
||||
7. **Preserve intent**, even if wording changes
|
||||
|
||||
## Example Workflow
|
||||
|
||||
1. Get commits: `git log v1.0.0..HEAD --no-merges`
|
||||
2. Parse each commit message
|
||||
3. Classify by type (feat/fix/etc.)
|
||||
4. Filter out internal commits
|
||||
5. Group by scope or feature
|
||||
6. Rephrase in user-facing language
|
||||
7. Map to changelog sections
|
||||
8. Deduplicate and clean up
|
||||
9. Format as changelog entries
|
||||
164
skills/mermaid-diagramming.md
Normal file
164
skills/mermaid-diagramming.md
Normal file
@@ -0,0 +1,164 @@
|
||||
---
|
||||
title: Mermaid Diagramming
|
||||
description: Mermaid syntax reference and diagram type selection
|
||||
tags: [mermaid, diagrams, visualization, architecture]
|
||||
---
|
||||
|
||||
# Mermaid Diagramming
|
||||
|
||||
## Metadata
|
||||
|
||||
**Purpose**: Mermaid syntax reference and best practices for all diagram types
|
||||
**Version**: 1.0.0
|
||||
|
||||
---
|
||||
|
||||
## Diagram Type Selection
|
||||
|
||||
| Diagram Type | Use When | Example Use Case |
|
||||
|-------------|----------|------------------|
|
||||
| **C4 Context** | System in environment | "How does our ML platform fit in the org?" |
|
||||
| **C4 Container** | Services and tech stack | "What are our main services?" |
|
||||
| **Flowchart** | Process flow, algorithms, decision trees | "How does model training work?" |
|
||||
| **Sequence** | Interactions over time, API calls | "What happens during API call?" |
|
||||
| **ER Diagram** | Database schemas, data models | "What's the feature store structure?" |
|
||||
| **Class** | OOP design, inheritance | "What's our model class hierarchy?" |
|
||||
| **State** | Entity lifecycles, state machines | "Model deployment states?" |
|
||||
| **Gantt** | Project timelines, schedules | "Release timeline?" |
|
||||
| **Journey** | User journeys, experiences | "User onboarding flow?" |
|
||||
| **Git Graph** | Branching strategies | "Release workflow?" |
|
||||
|
||||
## Syntax Examples
|
||||
|
||||
### C4 Context Diagram
|
||||
```mermaid
|
||||
C4Context
|
||||
title System Context
|
||||
|
||||
Person(user, "User", "Description")
|
||||
System(sys, "System", "What it does")
|
||||
System_Ext(external, "External System", "Description")
|
||||
|
||||
Rel(user, sys, "Uses", "HTTPS")
|
||||
Rel(sys, external, "Reads from", "API")
|
||||
```
|
||||
|
||||
### Flowchart
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start([Begin]) --> Step1[Process Data]
|
||||
Step1 --> Decision{Valid?}
|
||||
Decision -->|Yes| Step2[Continue]
|
||||
Decision -->|No| Error[Handle Error]
|
||||
Step2 --> End([Complete])
|
||||
Error --> End
|
||||
```
|
||||
|
||||
### Sequence Diagram
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
actor User
|
||||
participant API
|
||||
participant Service
|
||||
|
||||
User->>+API: Request
|
||||
API->>+Service: Process
|
||||
Service-->>-API: Result
|
||||
API-->>-User: Response
|
||||
```
|
||||
|
||||
### ER Diagram
|
||||
```mermaid
|
||||
erDiagram
|
||||
MODEL ||--o{ PREDICTION : generates
|
||||
MODEL {
|
||||
string model_id PK
|
||||
string name
|
||||
datetime created
|
||||
}
|
||||
PREDICTION {
|
||||
string id PK
|
||||
string model_id FK
|
||||
json result
|
||||
}
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
**Clarity**:
|
||||
- Use descriptive labels
|
||||
- Keep diagrams focused (one concern)
|
||||
- Avoid clutter
|
||||
- Add legends if needed
|
||||
|
||||
**Styling**:
|
||||
- Consistent naming
|
||||
- Logical flow direction
|
||||
- Group related items
|
||||
- Use color sparingly
|
||||
|
||||
**Maintainability**:
|
||||
- Add comments for complex parts
|
||||
- Structure code clearly
|
||||
- Make updates easy
|
||||
|
||||
## Common Patterns
|
||||
|
||||
**Direction**:
|
||||
```
|
||||
flowchart TD # Top-Down
|
||||
flowchart LR # Left-Right
|
||||
flowchart BT # Bottom-Top
|
||||
flowchart RL # Right-Left
|
||||
```
|
||||
|
||||
**Node shapes** (flowchart):
|
||||
```
|
||||
[Rectangle]
|
||||
(Rounded)
|
||||
([Stadium])
|
||||
[[Subroutine]]
|
||||
{Diamond}
|
||||
```
|
||||
|
||||
**Relationships** (sequence):
|
||||
```
|
||||
->> Solid arrow
|
||||
-->> Dotted arrow
|
||||
->>+ Activate
|
||||
-->>- Deactivate
|
||||
```
|
||||
|
||||
## Styling and Theming
|
||||
|
||||
**Standard colors for personal use diagrams**:
|
||||
```
|
||||
style Research fill:#fff4e6 # Light orange - research/experimental
|
||||
style Production fill:#e6f3ff # Light blue - production/library
|
||||
style Data fill:#e6ffe6 # Light green - data stores
|
||||
style External fill:#ffe6e6 # Light red - external systems
|
||||
```
|
||||
|
||||
**Subgraphs for boundaries**:
|
||||
```mermaid
|
||||
flowchart LR
|
||||
subgraph Research["Research Area"]
|
||||
N1[Notebook]
|
||||
end
|
||||
subgraph Production["Production"]
|
||||
S1[Service]
|
||||
end
|
||||
N1 -.-> S1
|
||||
```
|
||||
|
||||
**Provide both versions**:
|
||||
- Basic: Clean diagram without styling
|
||||
- Styled: With colors, themes, and visual enhancements
|
||||
|
||||
## Alignment with Repo-Investigator
|
||||
|
||||
When visualizing data/information flow (similar to `/repo-investigator:visualize-flow`):
|
||||
- Use **subgraphs** to distinguish Research vs Library boundaries
|
||||
- Use **dotted arrows** (-.->) for hand-off/promotion paths
|
||||
- Follow same color scheme: orange for research, blue for production
|
||||
- Show data sources, transformations, outputs, and consumers
|
||||
352
skills/readme-authoring.md
Normal file
352
skills/readme-authoring.md
Normal file
@@ -0,0 +1,352 @@
|
||||
---
|
||||
title: README Authoring
|
||||
description: Best practices and templates for generating README sections following standards
|
||||
tags: [readme, documentation, templates, authoring]
|
||||
---
|
||||
|
||||
# README Authoring Patterns
|
||||
|
||||
## Metadata
|
||||
|
||||
**Purpose**: Provide 8-section minimal README templates and generation patterns
|
||||
**Version**: 1.0.0
|
||||
|
||||
---
|
||||
|
||||
## Instructions
|
||||
|
||||
### Minimal README Structure
|
||||
|
||||
The Personal README follows an **8-section minimal structure** with a **link-first approach**:
|
||||
|
||||
1. **Project Title & One-Liner** - Name + 1-2 sentence description
|
||||
2. **Badges Block** *(optional)* - Version, lifecycle, docs, code style
|
||||
3. **Short Description** - Business problem/solution + core functionality (3-5 sentences)
|
||||
4. **Installation** - Simple command or link to detailed setup
|
||||
5. **Documentation** - Links to key resources (architecture, ADRs, guides)
|
||||
6. **Supporting Components** *(optional)* - Related repos/services
|
||||
7. **Contributing** - How to contribute or link to CONTRIBUTING.md
|
||||
8. **Bugs & Enhancements** - Issue tracker link
|
||||
|
||||
### Section Generation Reference
|
||||
|
||||
| Section | Template | Key Requirements | Common Sources |
|
||||
|---------|----------|------------------|----------------|
|
||||
| **1. Title & One-Liner** | `# {Name}`<br>`{1-2 sentence description}` | Project name + what it does | `pyproject.toml`, `package.json`, `setup.py` |
|
||||
| **2. Badges** *(optional)* | Wrapped in `<!-- badges: start/end -->` comments | MVP/Production tier - see badge options below | Version from metadata, lifecycle from tier, code style from `.pre-commit-config.yaml` |
|
||||
| **3. Description** | Business problem + solution + functionality (3-5 sentences) | Integrated business context (not separate sections) | `docs/`, code comments, metadata description |
|
||||
| **4. Installation** | Simple command + optional setup link | Actionable install command | Language-specific: `pip`, `npm`, `cargo` |
|
||||
| **5. Documentation** | Bulleted list of doc links | Only include links that exist | `docs/quickstart.md`, `docs/architecture.md`, `adr/` |
|
||||
| **6. Supporting Components** *(optional)* | Dependency list with links | Skip for standalone projects | Docker Compose, K8s configs, related repos |
|
||||
| **7. Contributing** | Link or inline guidance | Link to CONTRIBUTING.md if exists | `CONTRIBUTING.md`, `docs/contributing.md` |
|
||||
| **8. Bugs & Enhancements** | Issue tracker link | Clear call-to-action | GitHub Issues from git remote, or prompt user |
|
||||
|
||||
**Example (Prototype tier)**:
|
||||
```markdown
|
||||
# Customer Churn Predictor
|
||||
|
||||
Early-stage prototype for predicting customer churn using transaction history.
|
||||
|
||||
## Description
|
||||
|
||||
The marketing team needs to identify customers at risk of churning to target retention campaigns effectively. This prototype implements a gradient boosting classifier trained on transaction and engagement data to predict churn probability.
|
||||
|
||||
## Installation
|
||||
|
||||
\`\`\`bash
|
||||
pip install -e .
|
||||
\`\`\`
|
||||
|
||||
## Documentation
|
||||
|
||||
- See notebooks in `notebooks/` for exploratory analysis
|
||||
- Model card available in `docs/model-card.md`
|
||||
|
||||
## Contributing
|
||||
|
||||
This is an experimental prototype. For questions, contact the data science team.
|
||||
|
||||
## Bugs & Enhancements
|
||||
|
||||
Report issues via [GitHub Issues](https://github.com/USERNAME/churn-predictor/issues).
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Badge Options Reference
|
||||
|
||||
**Standard Personal badge format**:
|
||||
|
||||
Badges should be wrapped in HTML comments for maintainability:
|
||||
|
||||
```markdown
|
||||
<!-- badges: start -->
|
||||
[Badge 1]
|
||||
[Badge 2]
|
||||
...
|
||||
<!-- badges: end -->
|
||||
```
|
||||
|
||||
**Available badge types** (select based on project tier and applicability):
|
||||
|
||||
| Badge Type | Example | When to Use | Source |
|
||||
|------------|---------|-------------|--------|
|
||||
| **Version/Release** | `[](https://github.com/USERNAME/project/releases)` | All projects with releases | Git tags, `pyproject.toml`, `package.json` |
|
||||
| **Lifecycle** | `[](https://www.tidyverse.org/lifecycle/#experimental)` | All tiers (orange=prototype, yellow=mvp, green=production) | Project tier detection |
|
||||
| **Documentation** | `[](https://your-project-docs-url/)` | MVP/Production with published docs | Docs URL or relative link |
|
||||
| **Python Version** | `[](https://docs.python.org/3.12/)` | Python projects with version constraint | `pyproject.toml`, `setup.py`, `.python-version` |
|
||||
| **Code Style: black** | `[](https://github.com/psf/black)` | Python projects using black formatter | `.pre-commit-config.yaml`, `pyproject.toml` |
|
||||
| **Ruff** | `[](https://github.com/astral-sh/ruff)` | Python projects using ruff linter | `.pre-commit-config.yaml`, `pyproject.toml` |
|
||||
| **Pre-commit** | `[](https://github.com/pre-commit/pre-commit)` | Projects with pre-commit hooks | `.pre-commit-config.yaml` exists |
|
||||
|
||||
**Lifecycle badge color scheme**:
|
||||
- **Experimental/Prototype**: `orange` - Research, exploratory, not production-ready
|
||||
- **MVP/Maturing**: `yellow` - Pilot deployment, active development
|
||||
- **Stable/Production**: `green` - Production-ready, maintained
|
||||
|
||||
**Tier-specific badge recommendations**:
|
||||
|
||||
| **Tier** | **Recommended Badges** |
|
||||
|----------|------------------------|
|
||||
| **Prototype** | Optional: Version, Lifecycle (experimental-orange) |
|
||||
| **MVP** | Version, Lifecycle (mvp-yellow), Docs |
|
||||
| **Production** | Version, Lifecycle (stable-green), Docs, Python version (if applicable), Code style, Pre-commit |
|
||||
|
||||
**Detection logic**:
|
||||
|
||||
```python
|
||||
# Detect applicable badges from project files
|
||||
badges = []
|
||||
|
||||
# Version/Release (always try to detect)
|
||||
if has_git_tags or has_version_in_metadata:
|
||||
badges.append(("Releases", version_number, releases_url))
|
||||
|
||||
# Lifecycle (required for all tiers)
|
||||
tier = detect_project_tier() # prototype, mvp, production
|
||||
lifecycle_colors = {"prototype": "orange", "mvp": "yellow", "production": "green"}
|
||||
badges.append(("Lifecycle", tier, lifecycle_colors[tier]))
|
||||
|
||||
# Documentation (if docs exist)
|
||||
if docs_url or has_docs_directory:
|
||||
badges.append(("Docs", "latest", docs_url))
|
||||
|
||||
# Python-specific badges (only for Python projects)
|
||||
if is_python_project:
|
||||
if has_python_version_constraint:
|
||||
badges.append(("Python version", python_version, python_docs_url))
|
||||
|
||||
if uses_black_formatter:
|
||||
badges.append(("Code style: black", None, black_url))
|
||||
|
||||
if uses_ruff_linter:
|
||||
badges.append(("Ruff", None, ruff_badge_url))
|
||||
|
||||
# Pre-commit (language-agnostic)
|
||||
if has_precommit_config:
|
||||
badges.append(("pre-commit", "enabled", precommit_url))
|
||||
```
|
||||
|
||||
**Example badge blocks by tier**:
|
||||
|
||||
**Prototype tier** (minimal or no badges):
|
||||
```markdown
|
||||
<!-- badges: start -->
|
||||
[](https://www.tidyverse.org/lifecycle/#experimental)
|
||||
<!-- badges: end -->
|
||||
```
|
||||
|
||||
**MVP tier** (recommended badges):
|
||||
```markdown
|
||||
<!-- badges: start -->
|
||||
[](https://github.com/USERNAME/project/releases)
|
||||
[](https://www.tidyverse.org/lifecycle/#maturing)
|
||||
[](./docs/usage.md)
|
||||
<!-- badges: end -->
|
||||
```
|
||||
|
||||
**Production tier** (full badge set):
|
||||
```markdown
|
||||
<!-- badges: start -->
|
||||
[](https://github.com/USERNAME/project/releases)
|
||||
[](https://www.tidyverse.org/lifecycle/#stable)
|
||||
[](https://your-project-docs-url/)
|
||||
[](https://docs.python.org/3.12/)
|
||||
[](https://github.com/psf/black)
|
||||
[](https://github.com/astral-sh/ruff)
|
||||
[](https://github.com/pre-commit/pre-commit)
|
||||
<!-- badges: end -->
|
||||
```
|
||||
|
||||
**Important notes**:
|
||||
- Only include badges that are accurate and verifiable
|
||||
- Don't add Python-specific badges to non-Python projects
|
||||
- Badge URLs should link to meaningful resources (releases page, docs site, tool documentation)
|
||||
- Use HTML comment wrappers for easy maintenance
|
||||
|
||||
---
|
||||
|
||||
### Markdown Formatting Standards
|
||||
|
||||
**Heading hierarchy**:
|
||||
- `#` - Project title only
|
||||
- `##` - Section headings (Description, Installation, etc.)
|
||||
- `###` - Subsections (if needed, but keep minimal)
|
||||
|
||||
**Code blocks**:
|
||||
- Always specify language: \`\`\`bash, \`\`\`python, \`\`\`json
|
||||
- Use for installation commands, API examples
|
||||
|
||||
**Links**:
|
||||
- Relative links for internal docs: `[Setup](docs/setup.md)`
|
||||
- Absolute links for external resources: `[GitHub Issues](https://github.com/...)`
|
||||
- Use descriptive link text, not "click here"
|
||||
|
||||
**Lists**:
|
||||
- Use `-` for unordered lists (consistent with style)
|
||||
- Use `1.` for ordered lists (auto-numbering)
|
||||
|
||||
---
|
||||
|
||||
### Context Extraction Patterns
|
||||
|
||||
**Python projects** - Read these files in order:
|
||||
1. `pyproject.toml` - `project.name`, `project.description`, `project.version`
|
||||
2. `setup.py` - `name`, `description`, `version` if no pyproject.toml
|
||||
3. `requirements.txt` - Dependencies list
|
||||
4. Main module docstring - Business context
|
||||
|
||||
**JavaScript projects** - Read these files:
|
||||
1. `package.json` - `name`, `description`, `version`
|
||||
2. `README.md` - Existing content to preserve
|
||||
3. Main file docstring - Business context
|
||||
|
||||
**Documentation discovery**:
|
||||
- Architecture: `docs/architecture.md`, `*.drawio`, `*.mmd`
|
||||
- ADRs: `adr/`, `docs/adr/`
|
||||
- Setup: `docs/setup.md`, `docs/installation.md`, `INSTALL.md`
|
||||
- Contributing: `CONTRIBUTING.md`, `docs/contributing.md`
|
||||
|
||||
---
|
||||
|
||||
## Resources
|
||||
|
||||
### Tier-Specific README Example (MVP)
|
||||
|
||||
```markdown
|
||||
# Feature Store API
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
RESTful API for serving customer features to ML models and analytics tools.
|
||||
|
||||
## Description
|
||||
|
||||
Data scientists need consistent, versioned access to customer features across projects, but currently extract features redundantly from raw data sources. This API provides a centralized feature store with versioning, caching, and real-time serving (<50ms p95).
|
||||
|
||||
## Installation
|
||||
|
||||
\`\`\`bash
|
||||
pip install feature-store-client
|
||||
\`\`\`
|
||||
|
||||
For local development, see [Setup Guide](docs/setup.md).
|
||||
|
||||
## Documentation
|
||||
|
||||
- [Quickstart Guide](docs/quickstart.md) - Get started in 5 minutes
|
||||
- [API Reference](docs/api.md) - Complete endpoint documentation
|
||||
- [Architecture](docs/architecture.md) - System design and data flow
|
||||
- [ADRs](adr/) - Architecture Decision Records
|
||||
|
||||
## Supporting Components
|
||||
|
||||
- [Feature Pipeline](https://github.com/USERNAME/feature-pipeline) - Batch computation
|
||||
- [Redis Cluster](internal-link) - Cache layer
|
||||
|
||||
## Contributing
|
||||
|
||||
See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on reporting bugs, submitting changes, and running tests.
|
||||
|
||||
## Bugs & Enhancements
|
||||
|
||||
Report bugs via [GitHub Issues](https://github.com/USERNAME/feature-store-api/issues).
|
||||
```
|
||||
|
||||
**Tier variations**: Prototype skips badges/components; Production adds comprehensive docs (runbooks, monitoring, deployment guides).
|
||||
|
||||
**Business context integration**: See `readme-standards` skill "Before/After Examples" for good/bad business context patterns.
|
||||
|
||||
---
|
||||
|
||||
### Edge Case Handling
|
||||
|
||||
**No project metadata found**:
|
||||
- Prompt user: "What is the project name?"
|
||||
- Prompt user: "Provide a one-sentence description"
|
||||
|
||||
**No business context found**:
|
||||
- Prompt user: "What business problem does this solve?"
|
||||
- Prompt user: "What solution does this project provide?"
|
||||
- If user unsure: Generate technical description from code analysis
|
||||
|
||||
**No documentation exists**:
|
||||
```markdown
|
||||
## Documentation
|
||||
|
||||
- See inline code documentation and docstrings for implementation details
|
||||
- Architecture documentation coming soon
|
||||
|
||||
For questions, contact [team/person].
|
||||
```
|
||||
|
||||
**No CONTRIBUTING.md**:
|
||||
- Generate basic contributing section inline (see template above)
|
||||
- Suggest creating CONTRIBUTING.md for mature projects
|
||||
|
||||
**No tests detected**:
|
||||
- In Contributing section, note: "Please include tests with your contributions"
|
||||
- Don't specify test command if none exists
|
||||
|
||||
---
|
||||
|
||||
### Tier-Specific Variations
|
||||
|
||||
| **Section** | **Prototype** | **MVP** | **Production** |
|
||||
|-------------|---------------|---------|----------------|
|
||||
| **Badges** | Optional (skip) | Include basic badges | Full badge set |
|
||||
| **Description** | Brief (2-3 sentences) | Moderate (3-4 sentences) | Comprehensive (4-5 sentences) |
|
||||
| **Documentation Links** | Minimal (notebooks, basic docs) | Moderate (quickstart, API, architecture) | Comprehensive (all resources) |
|
||||
| **Supporting Components** | Usually none | May have 1-2 dependencies | Multiple service dependencies |
|
||||
| **Contributing** | Basic inline guidance | Link to CONTRIBUTING.md | Full process documentation |
|
||||
|
||||
---
|
||||
|
||||
### Link Validation
|
||||
|
||||
Before adding links to Documentation section:
|
||||
|
||||
1. **Verify file exists**: Use file system check
|
||||
2. **If missing**: Don't add placeholder link
|
||||
3. **Suggest creation**: Note in validation report that docs should be created
|
||||
|
||||
**Example validation logic**:
|
||||
```python
|
||||
docs_to_check = [
|
||||
("Quickstart", "docs/quickstart.md"),
|
||||
("Architecture", "docs/architecture.md"),
|
||||
("ADRs", "adr/"),
|
||||
]
|
||||
|
||||
valid_links = []
|
||||
for name, path in docs_to_check:
|
||||
if file_exists(path):
|
||||
valid_links.append((name, path))
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Remember**: The goal is **minimal, focused READMEs** that serve as clear entry points. Link to detailed documentation rather than embedding everything inline.
|
||||
421
skills/readme-standards.md
Normal file
421
skills/readme-standards.md
Normal file
@@ -0,0 +1,421 @@
|
||||
---
|
||||
title: README Standards
|
||||
description: Standard README structure and validation criteria for projects
|
||||
tags: [readme, documentation, standards, validation]
|
||||
---
|
||||
|
||||
# README Standards for Personal
|
||||
|
||||
## Metadata
|
||||
|
||||
**Purpose**: Define minimal README structure and validation rules
|
||||
**Version**: 1.0.0
|
||||
|
||||
---
|
||||
|
||||
## Instructions
|
||||
|
||||
### 8-Section Minimal Structure
|
||||
|
||||
All Personal READMEs must follow this **minimal structure**:
|
||||
|
||||
1. ✅ **Project Title & One-Liner** (REQUIRED)
|
||||
2. ℹ️ **Badges Block** (OPTIONAL - include for MVP/Production tiers)
|
||||
3. ✅ **Short Description** (REQUIRED - must integrate business problem/solution)
|
||||
4. ✅ **Installation** (REQUIRED)
|
||||
5. ✅ **Documentation** (REQUIRED - can be dedicated section or part of guides/resources section)
|
||||
6. ℹ️ **Supporting Components** (OPTIONAL - only if dependencies exist)
|
||||
7. ✅ **Contributing Link** (REQUIRED - can be dedicated section or link within documentation section)
|
||||
8. ✅ **Issue Reporting** (REQUIRED - can be dedicated bugs section or link within documentation/contributing)
|
||||
|
||||
**Key principles**:
|
||||
- **Link-first**: Point to detailed docs, don't embed everything inline
|
||||
- **Concise**: Keep README minimal, use links for depth
|
||||
- **Flexible structure**: Section names can vary (e.g., "Description" or "Overview", "Guides" can contain contributing/docs links)
|
||||
- **Essential content over format**: Ensure contributing links and issue reporting exist, regardless of exact section structure
|
||||
- **Actionable**: Clear installation steps and contribution guidance
|
||||
|
||||
---
|
||||
|
||||
### Section Validation Matrix
|
||||
|
||||
| Section | Heading | Required Content | Validation Checks |
|
||||
|---------|---------|------------------|-------------------|
|
||||
| **1. Title & One-Liner** | `# {Name}` | 1-2 sentence description | ✅ Title present<br>✅ Specific description (not vague) |
|
||||
| **2. Badges** *(optional)* | `<!-- badges: start -->`<br>`...badges...`<br>`<!-- badges: end -->` | Version, Lifecycle, Docs (MVP/Production)<br>+ Python version, Code Style, Pre-commit (Production Python projects) | ℹ️ Note if missing (MVP/Production tier)<br>✅ Wrapped in HTML comments<br>✅ shields.io format<br>✅ Lifecycle color matches tier (orange/yellow/green)<br>⚠️ Python badges on non-Python projects |
|
||||
| **3. Description** | `## Description` or `## Overview` | Business problem + solution + functionality (3-5 sentences) | ✅ Heading present (Description/Overview acceptable)<br>✅ Business context included<br>ℹ️ Separate Business Problem section allowed if brief |
|
||||
| **4. Installation** | `## Installation` | Actionable command + optional setup link | ✅ Code block with command<br>✅ Link to `docs/setup.md` if exists |
|
||||
| **5. Documentation** | `## Documentation` or within `## Guides` | Bulleted links (only existing docs) | ✅ 1+ link provided<br>✅ ADRs linked if `adr/` exists<br>✅ Links valid (no placeholders) |
|
||||
| **6. Supporting Components** *(optional)* | `## Supporting Components` | Dependency list with links | ℹ️ Skip for standalone projects<br>✅ Each dependency has link + description |
|
||||
| **7. Contributing Link** | `## Contributing` or within `## Documentation`/`## Guides` | Link to CONTRIBUTING.md or inline guidance | ✅ Contributing link/guidance present (dedicated section OR within docs section)<br>✅ Link if CONTRIBUTING.md exists<br>⚠️ Suggest CONTRIBUTING.md for MVP/Production |
|
||||
| **8. Issue Reporting** | `## Bugs`, `## Bugs & Enhancements`, or within `## Contributing` | Issue tracker link | ✅ Issue reporting link present (dedicated section OR within contributing/docs)<br>✅ Clear call-to-action |
|
||||
|
||||
**Common validation flags**:
|
||||
- ✅ **Compliant** - Section meets all requirements
|
||||
- ⚠️ **Incomplete** - Section present but missing key content
|
||||
- ❌ **Non-compliant** - Wrong structure (e.g., separate Business Problem section)
|
||||
- ℹ️ **Optional** - Note if missing but don't fail validation
|
||||
|
||||
---
|
||||
|
||||
### Tier-Specific Requirements
|
||||
|
||||
| **Section** | **Prototype** | **MVP** | **Production** |
|
||||
|-------------|---------------|---------|----------------|
|
||||
| **Title & One-Liner** | Required | Required | Required |
|
||||
| **Badges** | Optional (usually skip or lifecycle only) | Version, Lifecycle (yellow), Docs | Full set: Version, Lifecycle (green), Docs, Python version (if applicable), Code style, Pre-commit |
|
||||
| **Description** | Required (2-3 sentences) | Required (3-4 sentences) | Required (4-5 sentences) |
|
||||
| **Installation** | Required | Required | Required |
|
||||
| **Documentation** | Required (minimal) | Required (moderate) | Required (comprehensive) |
|
||||
| **Supporting Components** | Usually none | May have 1-2 | Often multiple |
|
||||
| **Contributing** | Required (inline OK) | Required (CONTRIBUTING.md preferred) | Required (CONTRIBUTING.md required) |
|
||||
| **Bugs** | Required | Required | Required |
|
||||
|
||||
**Tier detection signals**:
|
||||
- **Prototype**: No CI/CD, minimal tests, research-focused, `docs/` sparse
|
||||
- **MVP**: Basic CI/CD, test coverage setup, some docs, pilot deployment
|
||||
- **Production**: Full CI/CD, comprehensive tests, extensive docs, production deployment
|
||||
|
||||
---
|
||||
|
||||
### Link Validation Rules
|
||||
|
||||
**Required link checks**:
|
||||
1. **Architecture docs**: If `docs/architecture.md` or `.drawio` exists, must be linked in Documentation section
|
||||
2. **ADRs**: If `adr/` directory exists with ADRs, must be linked in Documentation section
|
||||
3. **CONTRIBUTING.md**: If exists, must be linked in Contributing section
|
||||
4. **Setup guide**: If `docs/setup.md` exists, should be linked in Installation section
|
||||
|
||||
**Broken link detection**:
|
||||
- Verify relative links point to existing files
|
||||
- Flag broken links as compliance issue
|
||||
- Don't flag external URLs (assume valid unless HTTP check requested)
|
||||
|
||||
---
|
||||
|
||||
### Common Compliance Issues
|
||||
|
||||
**Issue 1: Separate Business Problem/Solution sections**
|
||||
- ℹ️ Acceptable: `## Business Problem` and `## Solution` as separate sections (if brief and focused)
|
||||
- ✅ Preferred: Integrate into `## Description` or `## Overview` paragraph for conciseness
|
||||
|
||||
**Issue 2: Embedding full setup instructions**
|
||||
- ❌ Non-compliant: Detailed setup steps in README Installation section
|
||||
- ✅ Fix: Simple install command + link to `docs/setup.md`
|
||||
|
||||
**Issue 3: Missing business context**
|
||||
- ⚠️ Incomplete: Description only has technical details, no problem/solution context
|
||||
- ✅ Fix: Add sentence explaining what business problem this solves
|
||||
|
||||
**Issue 4: Placeholder documentation links**
|
||||
- ❌ Non-compliant: Linking to `docs/architecture.md` when file doesn't exist
|
||||
- ✅ Fix: Only link to docs that exist; note missing docs in validation report
|
||||
|
||||
**Issue 5: Testing instructions in README**
|
||||
- ❌ Non-compliant: Full testing guide embedded in README
|
||||
- ✅ Fix: Move testing instructions to `CONTRIBUTING.md`, link from README
|
||||
|
||||
**Issue 6: Missing badges for Production project**
|
||||
- ⚠️ Incomplete: Production-tier project without badges
|
||||
- ✅ Fix: Add full badge set (version, lifecycle-green, docs, Python version, code style, pre-commit)
|
||||
|
||||
**Issue 7: Badges not wrapped in HTML comments**
|
||||
- ⚠️ Incomplete: Badges present but missing `<!-- badges: start/end -->` wrappers
|
||||
- ✅ Fix: Wrap badge block in HTML comments for maintainability
|
||||
|
||||
**Issue 8: Incorrect lifecycle badge color**
|
||||
- ⚠️ Incomplete: MVP project with "experimental" (orange) badge instead of "mvp" (yellow)
|
||||
- ✅ Fix: Match lifecycle badge color to project tier (orange=prototype, yellow=mvp, green=production)
|
||||
|
||||
**Issue 9: Python badges on non-Python project**
|
||||
- ❌ Non-compliant: Python version, black, or ruff badges on JavaScript/other project
|
||||
- ✅ Fix: Remove language-specific badges from non-applicable projects
|
||||
|
||||
---
|
||||
|
||||
### Integration with MTPS (Minimum Transferrable Project Standards)
|
||||
|
||||
The README standards align with MTPS requirements:
|
||||
|
||||
**Documentation Standard** (from MTPS):
|
||||
- README.md with business problem, solution, setup → ✅ Covered by sections 1, 3, 4
|
||||
- Architecture diagram or description → ✅ Linked in Documentation section
|
||||
- Handoff summary → ✅ Separate document (not in README)
|
||||
|
||||
**README's role in MTPS**:
|
||||
- Entry point to project documentation
|
||||
- Links to architecture, ADRs, contributing guides
|
||||
- Does NOT replace comprehensive documentation
|
||||
- Minimal structure keeps it maintainable
|
||||
|
||||
---
|
||||
|
||||
## Resources
|
||||
|
||||
### Validation Checklist
|
||||
|
||||
Use this checklist when validating READMEs:
|
||||
|
||||
**Structure (8 sections)**:
|
||||
- [ ] Project Title & One-Liner present
|
||||
- [ ] Badges block (note if missing for MVP/Production, validate format if present)
|
||||
- [ ] Short Description present (## Description or ## Overview acceptable)
|
||||
- [ ] Installation section present
|
||||
- [ ] Documentation links present (dedicated section OR within ## Guides/etc.)
|
||||
- [ ] Supporting Components (note if missing, don't fail)
|
||||
- [ ] Contributing link present (dedicated section OR within ## Documentation/## Guides)
|
||||
- [ ] Issue reporting link present (dedicated ## Bugs section OR within ## Contributing/docs)
|
||||
|
||||
**Content Quality**:
|
||||
- [ ] One-liner is specific and descriptive
|
||||
- [ ] Badges wrapped in `<!-- badges: start/end -->` comments (if present)
|
||||
- [ ] Lifecycle badge color matches tier: orange (prototype), yellow (mvp), green (production)
|
||||
- [ ] No Python-specific badges on non-Python projects
|
||||
- [ ] Description includes business problem/solution context (integrated or separate sections acceptable)
|
||||
- [ ] Installation command is actionable
|
||||
- [ ] Documentation links are valid (point to existing files)
|
||||
- [ ] ADRs linked if `adr/` exists
|
||||
- [ ] CONTRIBUTING.md linked if exists (can be in dedicated section or docs/guides section)
|
||||
- [ ] Issue tracker link or reporting guidance provided (can be in dedicated section or contributing/docs section)
|
||||
|
||||
**Formatting**:
|
||||
- [ ] Proper heading hierarchy (`#` for title, `##` for sections)
|
||||
- [ ] Code blocks have language identifiers
|
||||
- [ ] Links use descriptive text
|
||||
- [ ] Consistent list formatting
|
||||
|
||||
**Tier-appropriate**:
|
||||
- [ ] Badges present for MVP/Production (optional for Prototype)
|
||||
- [ ] Badge set matches tier (MVP: basic set, Production: full set)
|
||||
- [ ] Documentation depth matches tier
|
||||
- [ ] CONTRIBUTING.md exists for MVP/Production
|
||||
|
||||
**Badge-specific validation** (if badges present):
|
||||
- [ ] Wrapped in HTML comments (`<!-- badges: start -->` ... `<!-- badges: end -->`)
|
||||
- [ ] Version/Release badge present (if project has releases)
|
||||
- [ ] Lifecycle badge present with correct color for tier
|
||||
- [ ] Docs badge present for MVP/Production (if docs exist)
|
||||
- [ ] Python version badge only on Python projects
|
||||
- [ ] Code style badges (black, ruff) only on Python projects with those tools
|
||||
- [ ] Pre-commit badge only if `.pre-commit-config.yaml` exists
|
||||
|
||||
---
|
||||
|
||||
### Compliance Report Format
|
||||
|
||||
When generating validation reports, use this format:
|
||||
|
||||
```markdown
|
||||
# README Validation Report
|
||||
|
||||
**Project**: {Project Name}
|
||||
**Date**: {Date}
|
||||
**Tier**: {Detected Tier}
|
||||
|
||||
## Summary
|
||||
|
||||
- ✅ {X} sections compliant
|
||||
- ⚠️ {Y} sections incomplete
|
||||
- ❌ {Z} sections missing
|
||||
|
||||
## Detailed Assessment
|
||||
|
||||
### ✅ Compliant Sections
|
||||
|
||||
1. **Title & One-Liner** - Clear and descriptive
|
||||
2. **Installation** - Simple command with link to setup guide
|
||||
3. **Bugs & Enhancements** - Issue tracker linked
|
||||
|
||||
### ⚠️ Incomplete Sections
|
||||
|
||||
4. **Short Description** - Missing business problem context
|
||||
- **Recommendation**: Add sentence explaining what business problem this solves
|
||||
|
||||
5. **Documentation** - Minimal links provided
|
||||
- **Recommendation**: Add links to architecture docs and ADRs (`adr/` exists but not linked)
|
||||
|
||||
### ❌ Missing Sections
|
||||
|
||||
6. **Contributing** - Section not found
|
||||
- **Recommendation**: Create Contributing section or add `CONTRIBUTING.md`
|
||||
|
||||
## Recommendations
|
||||
|
||||
1. **Priority 1 (Required)**:
|
||||
- Add Contributing section
|
||||
- Integrate business problem into Description
|
||||
|
||||
2. **Priority 2 (Suggested)**:
|
||||
- Link to existing ADRs in Documentation section
|
||||
- Create architecture documentation
|
||||
|
||||
3. **Priority 3 (Optional)**:
|
||||
- Add badges (project is MVP tier)
|
||||
- Create quickstart guide
|
||||
|
||||
## Next Steps
|
||||
|
||||
Run `/document-generator:update-readme` to automatically fix missing sections.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Before/After Examples
|
||||
|
||||
**Before (non-compliant)**:
|
||||
```markdown
|
||||
# My Project
|
||||
|
||||
This is a Python project.
|
||||
|
||||
## Setup
|
||||
|
||||
Install dependencies and run the code.
|
||||
|
||||
## Usage
|
||||
|
||||
See the code.
|
||||
```
|
||||
|
||||
**After (compliant - Prototype tier)**:
|
||||
```markdown
|
||||
# Customer Churn Predictor
|
||||
|
||||
Early-stage prototype for predicting customer churn using transaction history.
|
||||
|
||||
## Description
|
||||
|
||||
The marketing team needs to identify customers at risk of churning to target retention campaigns effectively. This prototype implements a gradient boosting classifier trained on transaction and engagement data to predict churn probability.
|
||||
|
||||
## Installation
|
||||
|
||||
\`\`\`bash
|
||||
pip install -e .
|
||||
\`\`\`
|
||||
|
||||
## Documentation
|
||||
|
||||
- See notebooks in `notebooks/` for exploratory analysis and model training
|
||||
- Model card available in `docs/model-card.md`
|
||||
|
||||
## Contributing
|
||||
|
||||
This is an experimental prototype. For questions or suggestions, contact the data science team.
|
||||
|
||||
## Bugs & Enhancements
|
||||
|
||||
Report issues via [GitHub Issues](https://github.com/USERNAME/churn-predictor/issues).
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Before (outdated structure)**:
|
||||
```markdown
|
||||
# Feature Store
|
||||
|
||||
## Business Problem
|
||||
Data scientists extract features redundantly.
|
||||
|
||||
## Solution
|
||||
Centralized feature store.
|
||||
|
||||
## Architecture
|
||||
[Architecture diagram here]
|
||||
|
||||
## Setup
|
||||
1. Install Python 3.9
|
||||
2. Install dependencies
|
||||
3. Configure database
|
||||
4. Run migrations
|
||||
5. Start server
|
||||
...
|
||||
|
||||
## Testing
|
||||
Run pytest with coverage.
|
||||
...
|
||||
```
|
||||
|
||||
**After (compliant - MVP tier)**:
|
||||
```markdown
|
||||
# Feature Store API
|
||||
|
||||
|
||||
|
||||
|
||||
RESTful API for serving customer features to ML models and analytics tools.
|
||||
|
||||
## Description
|
||||
|
||||
Data scientists and ML engineers need consistent, versioned access to customer features across multiple projects, but currently extract features redundantly from raw data sources. This API provides a centralized feature store with versioning, caching, and real-time serving capabilities.
|
||||
|
||||
## Installation
|
||||
|
||||
\`\`\`bash
|
||||
pip install feature-store-client
|
||||
\`\`\`
|
||||
|
||||
For local development setup, see [Setup Guide](docs/setup.md).
|
||||
|
||||
## Documentation
|
||||
|
||||
- [Quickstart Guide](docs/quickstart.md) - Get started in 5 minutes
|
||||
- [API Reference](docs/api.md) - Complete endpoint documentation
|
||||
- [Architecture](docs/architecture.md) - System design and data flow
|
||||
- [ADRs](adr/) - Architecture Decision Records
|
||||
|
||||
## Contributing
|
||||
|
||||
See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on reporting bugs, submitting changes, and running tests.
|
||||
|
||||
## Bugs & Enhancements
|
||||
|
||||
Report bugs and request features via [GitHub Issues](https://github.com/USERNAME/feature-store-api/issues).
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Tier-Specific Requirements Matrix
|
||||
|
||||
| **Validation Check** | **Prototype** | **MVP** | **Production** |
|
||||
|----------------------|---------------|---------|----------------|
|
||||
| **Title & One-Liner** | Required | Required | Required |
|
||||
| **Badges** | Optional | Recommended | Required |
|
||||
| **Description Length** | 2-3 sentences min | 3-4 sentences min | 4-5 sentences min |
|
||||
| **Business Context** | Preferred | Required | Required |
|
||||
| **Installation Command** | Required | Required | Required |
|
||||
| **Setup Guide Link** | Optional | Recommended | Required |
|
||||
| **Documentation Links** | 1+ link | 3+ links | 5+ links |
|
||||
| **Architecture Docs** | Optional | Recommended | Required |
|
||||
| **ADRs** | Optional | Recommended | Required (if exist) |
|
||||
| **CONTRIBUTING.md** | Optional | Recommended | Required |
|
||||
| **Supporting Components** | Usually none | If applicable | If applicable |
|
||||
| **Issue Tracker Link** | Required | Required | Required |
|
||||
|
||||
---
|
||||
|
||||
### Progressive Validation Approach
|
||||
|
||||
**Level 1: Structure** (must pass):
|
||||
- All 6 required sections present (Title, Description, Installation, Documentation, Contributing, Bugs)
|
||||
- Proper heading hierarchy
|
||||
|
||||
**Level 2: Content** (should pass):
|
||||
- Business problem/solution in Description
|
||||
- Actionable installation command
|
||||
- Valid documentation links
|
||||
- Clear contributing guidance
|
||||
|
||||
**Level 3: Quality** (nice to have):
|
||||
- Tier-appropriate badges
|
||||
- Comprehensive documentation links
|
||||
- CONTRIBUTING.md for mature projects
|
||||
- Architecture docs linked
|
||||
|
||||
**Scoring**:
|
||||
- **Level 1 pass** = Minimal compliance ✅
|
||||
- **Level 2 pass** = Standard compliance ✅✅
|
||||
- **Level 3 pass** = Excellent compliance ✅✅✅
|
||||
|
||||
---
|
||||
|
||||
**Remember**: The goal is **minimal, consistent READMEs** that serve as entry points. Link to comprehensive documentation rather than embedding everything inline.
|
||||
180
skills/version-validation.md
Normal file
180
skills/version-validation.md
Normal file
@@ -0,0 +1,180 @@
|
||||
---
|
||||
title: Version Validation
|
||||
description: Validation rules for semantic and calendar versioning
|
||||
tags: [versioning, semver, calver, validation]
|
||||
---
|
||||
|
||||
# Version Validation
|
||||
|
||||
## Metadata
|
||||
|
||||
**Purpose**: Validation rules for semantic and calendar versioning
|
||||
**Version**: 1.0.0
|
||||
|
||||
---
|
||||
|
||||
## Version Types
|
||||
|
||||
### Semantic Versioning (SemVer)
|
||||
|
||||
**Format**: `MAJOR.MINOR.PATCH` (e.g., 2.9.1)
|
||||
|
||||
**Rules**:
|
||||
- MAJOR: Breaking changes, incompatible API changes
|
||||
- MINOR: New features, backward-compatible
|
||||
- PATCH: Bug fixes, backward-compatible
|
||||
|
||||
**Examples**:
|
||||
- `1.0.0` - Initial stable release
|
||||
- `1.1.0` - Added new feature
|
||||
- `1.1.1` - Fixed bug
|
||||
- `2.0.0` - Breaking change
|
||||
|
||||
**Regex Pattern**: `^\d+\.\d+\.\d+$`
|
||||
|
||||
### Calendar Versioning (CalVer)
|
||||
|
||||
**Format**: `YYYY.MINOR` or `YYYY.MM.PATCH` (e.g., 2025.1 or 2025.11.2)
|
||||
|
||||
**Rules**:
|
||||
- YYYY: Year (4 digits)
|
||||
- MINOR: Sequential release number within year (starts at 1)
|
||||
- MM: Month (01-12)
|
||||
- PATCH: Bug fix number within month
|
||||
|
||||
**Examples**:
|
||||
- `2025.1` - First release of 2025
|
||||
- `2025.2` - Second release of 2025
|
||||
- `2025.11.1` - First patch in November 2025
|
||||
|
||||
**Regex Patterns**:
|
||||
- Year.Minor: `^\d{4}\.\d+$`
|
||||
- Year.Month.Patch: `^\d{4}\.(0[1-9]|1[0-2])\.\d+$`
|
||||
|
||||
## Version Detection
|
||||
|
||||
**Auto-detect version type** from existing versions:
|
||||
|
||||
1. Check existing changelog for version patterns
|
||||
2. Check git tags: `git tag --list`
|
||||
3. Check project metadata:
|
||||
- Python: `pyproject.toml` or `setup.py`
|
||||
- Node: `package.json`
|
||||
4. Default to SemVer if ambiguous
|
||||
|
||||
**Detection Logic**:
|
||||
```
|
||||
If version matches YYYY.N pattern → CalVer
|
||||
If version matches X.Y.Z pattern → SemVer
|
||||
If no existing versions → Ask user or default to SemVer
|
||||
```
|
||||
|
||||
## Validation Rules
|
||||
|
||||
### Chronological Ordering
|
||||
|
||||
Versions MUST appear in reverse chronological order (newest first):
|
||||
|
||||
**Correct**:
|
||||
```markdown
|
||||
## [2.1.0] - 2025-11-01
|
||||
## [2.0.0] - 2025-09-15
|
||||
## [1.5.0] - 2025-06-10
|
||||
```
|
||||
|
||||
**Incorrect**:
|
||||
```markdown
|
||||
## [1.5.0] - 2025-06-10
|
||||
## [2.0.0] - 2025-09-15 ❌ Out of order
|
||||
## [2.1.0] - 2025-11-01
|
||||
```
|
||||
|
||||
### Version Increment Rules
|
||||
|
||||
**SemVer**:
|
||||
- MAJOR increments reset MINOR and PATCH to 0 (2.3.1 → 3.0.0)
|
||||
- MINOR increments reset PATCH to 0 (2.3.1 → 2.4.0)
|
||||
- PATCH increments by 1 (2.3.1 → 2.3.2)
|
||||
|
||||
**CalVer (Year.Minor)**:
|
||||
- Year changes reset MINOR to 1 (2024.5 → 2025.1)
|
||||
- Within same year, MINOR increments (2025.1 → 2025.2)
|
||||
|
||||
**CalVer (Year.Month.Patch)**:
|
||||
- New month resets PATCH to 1 (2025.10.3 → 2025.11.1)
|
||||
- Within same month, PATCH increments (2025.11.1 → 2025.11.2)
|
||||
|
||||
### Date Validation
|
||||
|
||||
Dates MUST:
|
||||
- Use ISO format: `YYYY-MM-DD`
|
||||
- Be valid dates (no Feb 30, etc.)
|
||||
- Match or precede version dates in chronological order
|
||||
- Not be in the future (warning, not error)
|
||||
|
||||
**Regex**: `^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])$`
|
||||
|
||||
## Common Validation Errors
|
||||
|
||||
| Error Type | Example | Issue | Fix |
|
||||
|------------|---------|-------|-----|
|
||||
| **Invalid Version Format** | `## [v2.1.0] - 2025-11-01`<br>`## [2.1] - 2025-11-01`<br>`## [25.1] - 2025-11-01` | 'v' prefix in brackets<br>Incomplete SemVer (missing PATCH)<br>Incomplete year (use 2025, not 25) | Remove prefix, use complete version format |
|
||||
| **Incorrect Date Format** | `## [2.1.0] - 11/01/2025`<br>`## [2.1.0] - 2025-Nov-01`<br>`## [2.1.0] - 2025-11-1` | Wrong format (MM/DD/YYYY)<br>Month as text<br>Missing leading zero | Use `YYYY-MM-DD` format |
|
||||
| **Version Skip** | `## [2.1.0] - 2025-11-01`<br>`## [1.9.0] - 2025-09-15` | Skipped version 2.0.0 | Warning - may indicate missing entry |
|
||||
| **Date Ordering** | `## [2.1.0] - 2025-09-01`<br>`## [2.0.0] - 2025-11-01` | Later date for earlier version | Ensure dates are chronological |
|
||||
|
||||
## Version Comparison
|
||||
|
||||
**SemVer Comparison**:
|
||||
```
|
||||
2.1.0 > 2.0.5 > 2.0.0 > 1.9.9
|
||||
```
|
||||
|
||||
**CalVer Comparison** (Year.Minor):
|
||||
```
|
||||
2025.5 > 2025.1 > 2024.12 > 2024.1
|
||||
```
|
||||
|
||||
**CalVer Comparison** (Year.Month.Patch):
|
||||
```
|
||||
2025.11.2 > 2025.11.1 > 2025.10.5 > 2024.12.1
|
||||
```
|
||||
|
||||
## Auto-increment Logic
|
||||
|
||||
**SemVer**:
|
||||
- For features: Increment MINOR (2.1.3 → 2.2.0)
|
||||
- For fixes: Increment PATCH (2.1.3 → 2.1.4)
|
||||
- For breaking changes: Increment MAJOR (2.1.3 → 3.0.0)
|
||||
|
||||
**CalVer (Year.Minor)**:
|
||||
- Same year: Increment MINOR (2025.1 → 2025.2)
|
||||
- New year: Reset to YEAR.1 (2024.5 → 2025.1)
|
||||
|
||||
**CalVer (Year.Month.Patch)**:
|
||||
- Same month: Increment PATCH (2025.11.1 → 2025.11.2)
|
||||
- New month: YEAR.MONTH.1 (2025.10.3 → 2025.11.1)
|
||||
|
||||
## Validation Functions
|
||||
|
||||
**Validate version format**:
|
||||
- Match against regex for SemVer or CalVer
|
||||
- Return error if no match
|
||||
|
||||
**Validate version sequence**:
|
||||
- Parse all versions in changelog
|
||||
- Sort by version number
|
||||
- Check for correct ordering
|
||||
- Check for skipped versions
|
||||
|
||||
**Validate dates**:
|
||||
- Parse all dates
|
||||
- Check ISO format
|
||||
- Check chronological consistency
|
||||
- Warn if future dates
|
||||
|
||||
**Suggest next version**:
|
||||
- Detect version type
|
||||
- Analyze git history since last version
|
||||
- Apply increment rules
|
||||
- Return suggested version
|
||||
Reference in New Issue
Block a user