Initial commit
This commit is contained in:
Zhongwei Li
12
.claude-plugin/plugin.json
Normal file
12
.claude-plugin/plugin.json
Normal file
@@ -0,0 +1,12 @@
|
||||
{
|
||||
"name": "release-management",
|
||||
"description": "Automated release workflows, versioning, and deployment readiness tools",
|
||||
"version": "0.0.0-2025.11.28",
|
||||
"author": {
|
||||
"name": "Connor",
|
||||
"email": "noreply@claudex.dev"
|
||||
},
|
||||
"skills": [
|
||||
"./skills/semantic-release-tagger"
|
||||
]
|
||||
}
|
||||
3
README.md
Normal file
3
README.md
Normal file
@@ -0,0 +1,3 @@
|
||||
# release-management
|
||||
|
||||
Automated release workflows, versioning, and deployment readiness tools
|
||||
96
plugin.lock.json
Normal file
96
plugin.lock.json
Normal file
@@ -0,0 +1,96 @@
|
||||
{
|
||||
"$schema": "internal://schemas/plugin.lock.v1.json",
|
||||
"pluginId": "gh:cskiro/claudex:release-management",
|
||||
"normalized": {
|
||||
"repo": null,
|
||||
"ref": "refs/tags/v20251128.0",
|
||||
"commit": "c66a5eff275f460dc4bc99ef2652ec0037fd1c29",
|
||||
"treeHash": "2e27ecd2e79ff016e0dd1a7c2c035162d7517ee6deb45c79d9ea720031aee463",
|
||||
"generatedAt": "2025-11-28T10:15:55.783868Z",
|
||||
"toolVersion": "publish_plugins.py@0.2.0"
|
||||
},
|
||||
"origin": {
|
||||
"remote": "git@github.com:zhongweili/42plugin-data.git",
|
||||
"branch": "master",
|
||||
"commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390",
|
||||
"repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data"
|
||||
},
|
||||
"manifest": {
|
||||
"name": "release-management",
|
||||
"description": "Automated release workflows, versioning, and deployment readiness tools"
|
||||
},
|
||||
"content": {
|
||||
"files": [
|
||||
{
|
||||
"path": "README.md",
|
||||
"sha256": "3ba33284c638e0f50b679e6f8d9abb55d21b317fefcfda42cfa313b80ec2e07d"
|
||||
},
|
||||
{
|
||||
"path": ".claude-plugin/plugin.json",
|
||||
"sha256": "b126ee2888f1a25d00770cad9b8fa6ddcafd578820449645b7eaf19e7c46d3e2"
|
||||
},
|
||||
{
|
||||
"path": "skills/semantic-release-tagger/CHANGELOG.md",
|
||||
"sha256": "f0b9a63224f3814f51e7de5d5216eef497687478aadce50bb2ee05991d350c42"
|
||||
},
|
||||
{
|
||||
"path": "skills/semantic-release-tagger/README.md",
|
||||
"sha256": "18734455b44cadf8e6c0ec19b593c644c6d4101364b838ea5934fd8981616168"
|
||||
},
|
||||
{
|
||||
"path": "skills/semantic-release-tagger/SKILL.md",
|
||||
"sha256": "ff9a317ac03bdb28d2251a9d20749ef980c2350b7ed6849d37ce7ee4a7f58514"
|
||||
},
|
||||
{
|
||||
"path": "skills/semantic-release-tagger/examples/tag-examples.md",
|
||||
"sha256": "8603511c3dc174025f968497de7a7fda1b9694b4a069983e7b9ea877fd57ce0c"
|
||||
},
|
||||
{
|
||||
"path": "skills/semantic-release-tagger/workflow/phase-1-convention.md",
|
||||
"sha256": "9f6f9a10de8b43aa8ad5870197fcd1f7d949523c13a5e03704378ebd6c5d10ca"
|
||||
},
|
||||
{
|
||||
"path": "skills/semantic-release-tagger/workflow/phase-5-maintenance.md",
|
||||
"sha256": "18aed8281e49f0b76f5e7fe98d8bf556fd6c0d434e69d8c810e0b95f6db61b9d"
|
||||
},
|
||||
{
|
||||
"path": "skills/semantic-release-tagger/workflow/phase-3-create-tag.md",
|
||||
"sha256": "a6eb7a6710aa3d809834d7880fc6e4f4d7e45269fd9c584655cc06057c4be1d9"
|
||||
},
|
||||
{
|
||||
"path": "skills/semantic-release-tagger/workflow/phase-0-auto-analysis.md",
|
||||
"sha256": "8e368809143deef5b284914050f7c136647b0a7ed75c4d5be3aab91f4a8b7b78"
|
||||
},
|
||||
{
|
||||
"path": "skills/semantic-release-tagger/workflow/phase-4-github-release.md",
|
||||
"sha256": "605bd0f6092df1cfe15a1161153c322145b70e8f5a1ab10247c6bd6f2a2e26eb"
|
||||
},
|
||||
{
|
||||
"path": "skills/semantic-release-tagger/workflow/phase-2-version.md",
|
||||
"sha256": "cd9130426fdcae9a475cf10dd0f0cd0710465f8c2fb360121fee0f5b961d4da7"
|
||||
},
|
||||
{
|
||||
"path": "skills/semantic-release-tagger/data/insights-reference.md",
|
||||
"sha256": "87fb4e6d834a0e5bd5ee08e198b306d737a8805ef5ad7aadd1c0a33c0f05d5d9"
|
||||
},
|
||||
{
|
||||
"path": "skills/semantic-release-tagger/reference/best-practices.md",
|
||||
"sha256": "1c87de51479d149c4cae9982d514df1d34c1bfb775c9001e22eaebe3073059f5"
|
||||
},
|
||||
{
|
||||
"path": "skills/semantic-release-tagger/reference/troubleshooting.md",
|
||||
"sha256": "f7276020acc202ea5e9c3cf477a8ad3bfd1f07d4984e4820102bc5aa48fda524"
|
||||
},
|
||||
{
|
||||
"path": "skills/semantic-release-tagger/reference/.gitkeep",
|
||||
"sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
|
||||
}
|
||||
],
|
||||
"dirSha256": "2e27ecd2e79ff016e0dd1a7c2c035162d7517ee6deb45c79d9ea720031aee463"
|
||||
},
|
||||
"security": {
|
||||
"scannedAt": null,
|
||||
"scannerVersion": null,
|
||||
"flags": []
|
||||
}
|
||||
}
|
||||
16
skills/semantic-release-tagger/CHANGELOG.md
Normal file
16
skills/semantic-release-tagger/CHANGELOG.md
Normal file
@@ -0,0 +1,16 @@
|
||||
# Changelog
|
||||
|
||||
## 0.2.0
|
||||
|
||||
- Refactored to Anthropic progressive disclosure pattern
|
||||
- Updated description with "Use PROACTIVELY when..." format
|
||||
- Removed version/author/category/tags from frontmatter
|
||||
|
||||
## 0.1.0
|
||||
|
||||
- Initial marketplace release - Automated git tagging agent for semantic versioning
|
||||
- Phase 0 auto-context analysis with tag convention detection
|
||||
- Intelligent version calculation from conventional commits
|
||||
- Automated tag creation with pre-flight validation
|
||||
- GitHub release integration with auto-generated changelogs
|
||||
- Monorepo support with component-specific versioning
|
||||
80
skills/semantic-release-tagger/README.md
Normal file
80
skills/semantic-release-tagger/README.md
Normal file
@@ -0,0 +1,80 @@
|
||||
# Semantic Release Tagger
|
||||
|
||||
Automated git tagging agent that analyzes your repository, parses conventional commits, recommends semantic versions, and executes tag creation with your confirmation.
|
||||
|
||||
## Overview
|
||||
|
||||
This skill is an **interactive automation agent** that handles the complete git tagging workflow. It analyzes repository state, detects existing conventions, parses conventional commits to determine version bumps, and executes tag creation commands with your confirmation.
|
||||
|
||||
## Installation
|
||||
|
||||
Install from the Claudex marketplace using Claude Code.
|
||||
|
||||
## Quick Start
|
||||
|
||||
Invoke this skill when you need help with:
|
||||
- "how should I tag this release?"
|
||||
- "version this component"
|
||||
- "create semantic git tags"
|
||||
- "monorepo versioning strategy"
|
||||
|
||||
The skill will automatically:
|
||||
1. **Analyze your repository** - Detect tags, conventions, and recent commits
|
||||
2. **Calculate next version** - Parse conventional commits for intelligent version bumps
|
||||
3. **Recommend tag** - Present findings and suggested version
|
||||
4. **Execute after confirmation** - Create and push tag with one command
|
||||
5. **Optionally create GitHub release** - Auto-generated changelog from commits
|
||||
|
||||
## Trigger Phrases
|
||||
|
||||
- "how should I tag this release?"
|
||||
- "version this component"
|
||||
- "create semantic git tags"
|
||||
- "tag naming convention"
|
||||
- "monorepo versioning strategy"
|
||||
- "git tag vs github release"
|
||||
- "semantic versioning guidance"
|
||||
|
||||
## Features
|
||||
|
||||
- ✅ **Automated context analysis** - Auto-detects existing patterns
|
||||
- ✅ **Conventional commit parsing** - Intelligent MAJOR/MINOR/PATCH detection
|
||||
- ✅ **Command execution** - Creates and pushes tags after confirmation
|
||||
- ✅ **Monorepo support** - Component-specific versioning with namespaces
|
||||
- ✅ **GitHub release integration** - Auto-generated changelogs
|
||||
- ✅ **Consistency auditing** - Detects mixed tag conventions
|
||||
- ✅ **CI/CD patterns** - Tag filtering for automation
|
||||
|
||||
## Workflow
|
||||
|
||||
1. **Phase 0: Auto-Analysis** (runs automatically)
|
||||
- Detects tag conventions, latest versions, commits since last tag
|
||||
2. **Phase 1: Convention Selection** (if needed)
|
||||
- Choose namespace pattern for monorepos
|
||||
3. **Phase 2: Version Calculation** (automated)
|
||||
- Parse conventional commits, determine version bump
|
||||
4. **Phase 3: Tag Creation** (after confirmation)
|
||||
- Execute git tag and push commands
|
||||
5. **Phase 4: GitHub Release** (optional)
|
||||
- Create release with auto-generated changelog
|
||||
|
||||
## Documentation
|
||||
|
||||
See [SKILL.md](SKILL.md) for complete documentation including:
|
||||
- Detailed workflow phases
|
||||
- Conventional commit parsing rules
|
||||
- Tag naming convention trade-offs
|
||||
- Troubleshooting guide
|
||||
- Real-world examples
|
||||
|
||||
## Source
|
||||
|
||||
Generated from 7 production insights from version-control workflows (2025-11-14 to 2025-11-15).
|
||||
|
||||
## Version
|
||||
|
||||
0.1.0 - Initial marketplace release
|
||||
|
||||
## License
|
||||
|
||||
Part of the Claudex marketplace.
|
||||
85
skills/semantic-release-tagger/SKILL.md
Normal file
85
skills/semantic-release-tagger/SKILL.md
Normal file
@@ -0,0 +1,85 @@
|
||||
---
|
||||
name: semantic-release-tagger
|
||||
description: Use PROACTIVELY when creating releases after PR merges to main, or when user asks about versioning strategy. Automated git tagging agent that analyzes repository state, parses conventional commits, calculates semantic versions, and creates annotated git tags with GitHub releases. Supports monorepo namespaced tags with @ separator convention. Not for changelog generation or pre-release/alpha versioning.
|
||||
---
|
||||
|
||||
# Semantic Release Tagger
|
||||
|
||||
## Overview
|
||||
|
||||
This skill is an **interactive automation agent** that handles the complete git tagging workflow. It analyzes your repository state, detects existing conventions, parses conventional commits to determine version bumps, and executes tag creation commands with your confirmation.
|
||||
|
||||
**Key Capabilities**:
|
||||
- **Auto-analyze repository context**: Detect existing tags, conventions, and monorepo structure
|
||||
- **Intelligent version calculation**: Parse conventional commits (feat/fix/BREAKING) to determine MAJOR.MINOR.PATCH bumps
|
||||
- **Automated tag creation**: Execute git commands after user confirmation
|
||||
- **GitHub release integration**: Optional release creation with auto-generated changelog
|
||||
- **Monorepo awareness**: Component-specific versioning with namespace support
|
||||
|
||||
## When to Use This Skill
|
||||
|
||||
**Trigger Phrases**:
|
||||
- "how should I tag this release?"
|
||||
- "version this component"
|
||||
- "create semantic git tags"
|
||||
- "The PR was merged, create a release"
|
||||
|
||||
**Use PROACTIVELY when**:
|
||||
- User is about to create a release or tag
|
||||
- User asks about versioning strategy
|
||||
- User mentions monorepo or multi-component versioning
|
||||
|
||||
**Do NOT use when**:
|
||||
- User wants to create a branch (not a tag)
|
||||
- User is working with version numbers in code (package.json)
|
||||
- User needs changelog generation (use release-management skill)
|
||||
|
||||
## Response Style
|
||||
|
||||
**Interactive Automation Agent**: Automatically analyze repository state, present findings with recommendations, get user confirmation, then execute commands.
|
||||
|
||||
**Execution Pattern**:
|
||||
1. **Auto-execute**: Run git commands to gather context
|
||||
2. **Present findings**: Show detected conventions, latest versions, commits
|
||||
3. **Recommend action**: Calculate next version based on commits
|
||||
4. **Confirm with user**: "Create tag `component@X.Y.Z`?"
|
||||
5. **Execute**: Run git tag/push commands
|
||||
6. **Verify**: Show results and next steps
|
||||
|
||||
## Workflow
|
||||
|
||||
| Phase | Description | Details |
|
||||
|-------|-------------|---------|
|
||||
| 0 | Auto-Context Analysis | → [workflow/phase-0-auto-analysis.md](workflow/phase-0-auto-analysis.md) |
|
||||
| 1 | Choose Tag Convention | → [workflow/phase-1-convention.md](workflow/phase-1-convention.md) |
|
||||
| 2 | Determine Version Number | → [workflow/phase-2-version.md](workflow/phase-2-version.md) |
|
||||
| 3 | Create Git Tags | → [workflow/phase-3-create-tag.md](workflow/phase-3-create-tag.md) |
|
||||
| 4 | Create GitHub Release | → [workflow/phase-4-github-release.md](workflow/phase-4-github-release.md) |
|
||||
| 5 | Maintain Tag History | → [workflow/phase-5-maintenance.md](workflow/phase-5-maintenance.md) |
|
||||
|
||||
## Quick Reference
|
||||
|
||||
### Version Bump Rules
|
||||
|
||||
| Change Type | Example | Version Bump |
|
||||
|-------------|---------|--------------|
|
||||
| BREAKING CHANGE | API removal | MAJOR (2.0.0) |
|
||||
| feat: | New feature | MINOR (1.3.0) |
|
||||
| fix: / chore: | Bug fix | PATCH (1.2.4) |
|
||||
| First release | N/A | 0.1.0 |
|
||||
|
||||
### Tag Convention Options
|
||||
|
||||
- **NPM-style @** (recommended): `marketplace@1.0.0`
|
||||
- **Slash-based**: `marketplace/v1.0.0`
|
||||
- **Flat**: `v1.0.0` (single component only)
|
||||
|
||||
## Reference Materials
|
||||
|
||||
- [Best Practices](reference/best-practices.md)
|
||||
- [Troubleshooting](reference/troubleshooting.md)
|
||||
|
||||
## Metadata
|
||||
|
||||
**Category**: release-management
|
||||
**Source**: Generated from 7 insights (docs/lessons-learned/version-control/)
|
||||
224
skills/semantic-release-tagger/data/insights-reference.md
Normal file
224
skills/semantic-release-tagger/data/insights-reference.md
Normal file
@@ -0,0 +1,224 @@
|
||||
# Insights Reference - Git Tagging & Versioning Strategy
|
||||
|
||||
This document consolidates all source insights used to generate the git-tagging-strategy skill.
|
||||
|
||||
## Overview
|
||||
|
||||
- **Total Insights**: 7
|
||||
- **Date Range**: 2025-11-14 to 2025-11-15
|
||||
- **Categories**: version-control
|
||||
- **Sessions**: 3 unique sessions
|
||||
- **Source Directory**: `docs/lessons-learned/version-control/`
|
||||
|
||||
---
|
||||
|
||||
## Insight 1: Semantic Git Tagging Strategy
|
||||
|
||||
**Source**: `2025-11-14-semantic-git-tagging-strategy.md`
|
||||
**Session**: 63c56792-8274-4f35-8800-0f7ed2fe422a
|
||||
**Date**: 2025-11-14
|
||||
|
||||
### Content
|
||||
|
||||
Using hierarchical tag namespaces (`marketplace/v1.0.0`, `hook/{name}/v2.1.0`) provides semantic organization for multi-component repositories:
|
||||
|
||||
**Benefits**:
|
||||
1. **Component-specific versioning** - Each component can evolve independently
|
||||
2. **Clear ownership** - Tag prefix indicates what's being versioned
|
||||
3. **Git tag filtering** - `git tag -l "hook/*"` lists all hook versions
|
||||
4. **Release automation** - CI/CD can trigger on specific tag patterns
|
||||
|
||||
**Convention**:
|
||||
- `marketplace/vX.Y.Z` - Overall marketplace/plugin structure version
|
||||
- `hook/{name}/vX.Y.Z` - Individual hook versions
|
||||
- `skill/{name}/vX.Y.Z` - Individual skill versions
|
||||
- `agent/{name}/vX.Y.Z` - Individual agent versions
|
||||
|
||||
This scales better than flat versioning (`v1.0.0`, `v2.0.0`) in monorepos with multiple independently-versioned components.
|
||||
|
||||
### Skill Integration
|
||||
|
||||
- **Phase 1**: Informs slash-based namespace option
|
||||
- **Phase 5**: Provides tag filtering examples
|
||||
|
||||
---
|
||||
|
||||
## Insight 2: NPM-Style Git Tagging Convention
|
||||
|
||||
**Source**: `2025-11-14-npm-style-git-tagging-convention.md`
|
||||
**Session**: 63c56792-8274-4f35-8800-0f7ed2fe422a
|
||||
**Date**: 2025-11-14
|
||||
|
||||
### Content
|
||||
|
||||
Using `@` instead of `/v` for version separators (`package@1.0.0` vs `package/v1.0.0`) aligns with npm's scoped package convention and provides cleaner semantics:
|
||||
|
||||
**Advantages of `@` convention**:
|
||||
1. **npm familiarity** - Developers recognize `@scope/package@version` pattern
|
||||
2. **Cleaner URLs** - `tag/marketplace@1.0.0` vs `tag/marketplace/v1.0.0`
|
||||
3. **Semantic clarity** - `@` clearly separates name from version
|
||||
4. **Path safety** - No confusion with directory separators
|
||||
|
||||
**Version numbering**:
|
||||
- Start at `0.1.0` for initial public releases (not 1.0.0 or 2.1.0)
|
||||
- Component version ≠ internal script version
|
||||
- Follows semver: MAJOR.MINOR.PATCH
|
||||
|
||||
The `v` prefix is optional with `@` convention since the separator itself indicates versioning, keeping tags minimal and readable.
|
||||
|
||||
### Skill Integration
|
||||
|
||||
- **Phase 1**: Informs npm-style @ separator option
|
||||
- **Phase 2**: Provides version numbering guidance (start at 0.1.0)
|
||||
|
||||
---
|
||||
|
||||
## Insight 3: Git Tags vs GitHub Releases
|
||||
|
||||
**Source**: `2025-11-14-git-tags-vs-github-releases-git-tags-are-lightweig.md`
|
||||
**Session**: 1b1069bf-67be-45a3-ae42-dc32fd30d2ee
|
||||
**Date**: 2025-11-14
|
||||
|
||||
### Content
|
||||
|
||||
Git tags are lightweight version markers in your repository history, while GitHub releases are feature-rich with changelog generation, asset uploads, and notification systems. Tags are required for releases, but releases add discoverability and user-friendly documentation on the GitHub interface.
|
||||
|
||||
**Tag Naming Convention**: Using `v1.1.1` (with v prefix) is a common convention that distinguishes version tags from other tags, though your existing releases use `marketplace@1.1.0` format for namespace clarity.
|
||||
|
||||
### Skill Integration
|
||||
|
||||
- **Phase 4**: Explains git tags vs GitHub releases trade-offs
|
||||
- **Important Reminders**: "Git tags ≠ GitHub releases"
|
||||
|
||||
---
|
||||
|
||||
## Insight 4: Namespace Tag Conventions
|
||||
|
||||
**Source**: `2025-11-14-namespace-tag-conventions-the-marketplacexyz-forma.md`
|
||||
**Session**: 1b1069bf-67be-45a3-ae42-dc32fd30d2ee
|
||||
**Date**: 2025-11-14
|
||||
|
||||
### Content
|
||||
|
||||
The `marketplace@X.Y.Z` format provides namespace clarity in monorepos or multi-component projects, making it immediately clear which part of the system the version applies to. This is especially valuable when a repository might have multiple releasable components (marketplace, CLI tools, libraries, etc.).
|
||||
|
||||
### Skill Integration
|
||||
|
||||
- **Phase 1**: Reinforces namespace clarity benefit
|
||||
- **Troubleshooting**: "Monorepo tags confusing" section
|
||||
|
||||
---
|
||||
|
||||
## Insight 5: Semantic Versioning
|
||||
|
||||
**Source**: `2025-11-14-semantic-versioning-the-patch-version-bump-110-111.md`
|
||||
**Session**: 1b1069bf-67be-45a3-ae42-dc32fd30d2ee
|
||||
**Date**: 2025-11-14
|
||||
|
||||
### Content
|
||||
|
||||
The patch version bump (1.1.0 → 1.1.1) correctly signals a bug fix release per SemVer conventions. This communicates to users that the changes are backward-compatible fixes without new features or breaking changes.
|
||||
|
||||
**PR Workflow**: Pushing additional commits to a PR branch automatically updates the PR and triggers CI re-runs if configured, enabling iterative refinement before merge.
|
||||
|
||||
### Skill Integration
|
||||
|
||||
- **Phase 2**: Provides semantic versioning rules and examples
|
||||
- **Version bump table**: PATCH example (1.2.3 → 1.2.4)
|
||||
|
||||
---
|
||||
|
||||
## Insight 6: Fast-Forward Merges
|
||||
|
||||
**Source**: `2025-11-15-fast-forward-merges-the-fast-forward-message-indic.md`
|
||||
**Session**: 1b1069bf-67be-45a3-ae42-dc32fd30d2ee
|
||||
**Date**: 2025-11-15
|
||||
|
||||
### Content
|
||||
|
||||
The "Fast-forward" message indicates GitHub merged these PRs by moving the main branch pointer forward without creating merge commits, keeping a linear history. This happens when the PR branch is directly ahead of main with no conflicting changes.
|
||||
|
||||
### Skill Integration
|
||||
|
||||
- **Phase 5**: Fast-forward merge awareness
|
||||
- **Important Reminders**: "Fast-forward merges preserve history"
|
||||
|
||||
---
|
||||
|
||||
## Insight 7: Tagging Convention
|
||||
|
||||
**Source**: `2025-11-14-tagging-convention-your-versioning-follows-a-clear.md`
|
||||
**Session**: 43c2ed05-2280-4184-ae3d-27a30297634d
|
||||
**Date**: 2025-11-14
|
||||
|
||||
### Content
|
||||
|
||||
Your versioning follows a clear pattern:
|
||||
- Marketplace: `marketplace@<semver>`
|
||||
- Skills: `<skill-name>@<semver>`
|
||||
|
||||
This enables independent versioning of skills while tracking the overall marketplace evolution. The tags serve as immutable release markers for users and automated deployment systems.
|
||||
|
||||
**Release Readiness**: With both PR merge and tags complete, the JSON Structured Outputs skill suite is now:
|
||||
- Discoverable in the marketplace
|
||||
- Versioned for dependency management
|
||||
- Ready for distribution/installation
|
||||
|
||||
### Skill Integration
|
||||
|
||||
- **Phase 1**: Real-world example of @ convention
|
||||
- **Important Reminders**: "Tags are immutable"
|
||||
|
||||
---
|
||||
|
||||
## Insight-to-Skill Mapping
|
||||
|
||||
| Insight | SKILL.md Section | Contribution |
|
||||
|---------|------------------|--------------|
|
||||
| Semantic Git Tagging | Phase 1, Phase 5 | Slash-based namespace option, tag filtering |
|
||||
| NPM-Style Convention | Phase 1, Phase 2 | @ separator option, version numbering rules |
|
||||
| Git Tags vs Releases | Phase 4, Reminders | Trade-offs explanation, relationship clarity |
|
||||
| Namespace Conventions | Phase 1, Troubleshooting | Namespace clarity benefits, monorepo guidance |
|
||||
| Semantic Versioning | Phase 2 | Version bump rules, PATCH example |
|
||||
| Fast-Forward Merges | Phase 5, Reminders | Linear history awareness |
|
||||
| Tagging Convention | Phase 1, Reminders | Real-world example, immutability principle |
|
||||
|
||||
---
|
||||
|
||||
## Clustering Analysis
|
||||
|
||||
**Similarity Score**: 0.82 (high cohesion)
|
||||
|
||||
**Common Keywords**:
|
||||
- git, tag, version, semantic, namespace, release, convention, monorepo
|
||||
|
||||
**Temporal Proximity**:
|
||||
- 6 of 7 insights from 2025-11-14 (same day)
|
||||
- 1 insight from 2025-11-15 (next day)
|
||||
|
||||
**Category Alignment**:
|
||||
- All from version-control category (100%)
|
||||
|
||||
**Workflow Coherence**:
|
||||
- All insights relate to the tag creation and management lifecycle
|
||||
- Natural progression: Choose convention → Calculate version → Create tag → Manage history
|
||||
|
||||
---
|
||||
|
||||
## Quality Assessment
|
||||
|
||||
- ✅ **Actionable**: All insights provide concrete guidance
|
||||
- ✅ **Non-redundant**: Each insight covers unique aspect of tagging
|
||||
- ✅ **Production-tested**: Insights from real release workflows
|
||||
- ✅ **Well-documented**: Clear examples and rationale provided
|
||||
- ✅ **Complementary**: Insights build on each other cohesively
|
||||
|
||||
---
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
Potential additions to this skill based on related insights:
|
||||
- GitHub Actions workflow examples for automated tagging
|
||||
- Integration with changelog generation tools
|
||||
- Pre-commit hooks for tag validation
|
||||
- Tag protection rules configuration
|
||||
377
skills/semantic-release-tagger/examples/tag-examples.md
Normal file
377
skills/semantic-release-tagger/examples/tag-examples.md
Normal file
@@ -0,0 +1,377 @@
|
||||
# Tag Creation Examples
|
||||
|
||||
Real-world tagging scenarios with complete commands and explanations.
|
||||
|
||||
---
|
||||
|
||||
## Scenario 1: First Release of a New Project
|
||||
|
||||
**Context**: You've built a new CLI tool and want to create the first release.
|
||||
|
||||
**Recommended Convention**: Flat tags (`vX.Y.Z`) since single component
|
||||
|
||||
**Steps**:
|
||||
|
||||
```bash
|
||||
# 1. Verify no existing tags
|
||||
git tag -l
|
||||
# Output: (empty)
|
||||
|
||||
# 2. Choose version: 0.1.0 (initial public release)
|
||||
|
||||
# 3. Create annotated tag
|
||||
git tag -a "v0.1.0" -m "Release v0.1.0 - Initial public release"
|
||||
|
||||
# 4. Verify tag
|
||||
git show v0.1.0
|
||||
# Shows tag metadata and commit details
|
||||
|
||||
# 5. Push tag to remote
|
||||
git push origin v0.1.0
|
||||
|
||||
# 6. Create GitHub release
|
||||
gh release create v0.1.0 \
|
||||
--title "CLI Tool v0.1.0" \
|
||||
--notes "Initial release with core functionality"
|
||||
```
|
||||
|
||||
**Result**: Tag `v0.1.0` created and pushed, GitHub release published
|
||||
|
||||
---
|
||||
|
||||
## Scenario 2: Monorepo with Multiple Components (npm-style)
|
||||
|
||||
**Context**: Monorepo with marketplace, hooks, and skills. Using npm-style `@` separator.
|
||||
|
||||
**Recommended Convention**: `component@X.Y.Z`
|
||||
|
||||
**Steps**:
|
||||
|
||||
```bash
|
||||
# 1. Check existing tags
|
||||
git tag -l "marketplace@*" --sort=-v:refname | head -3
|
||||
# Output:
|
||||
# marketplace@1.1.0
|
||||
# marketplace@1.0.0
|
||||
# marketplace@0.1.0
|
||||
|
||||
# 2. Analyze changes since 1.1.0
|
||||
git log marketplace@1.1.0..HEAD --oneline
|
||||
# Shows: 2 commits with bug fixes
|
||||
|
||||
# 3. Determine version: 1.1.1 (PATCH bump for bug fixes)
|
||||
|
||||
# 4. Create annotated tag
|
||||
git tag -a "marketplace@1.1.1" -m "Release marketplace 1.1.1"
|
||||
|
||||
# 5. Push tag
|
||||
git push origin marketplace@1.1.1
|
||||
|
||||
# 6. Tag a hook in same repo
|
||||
git tag -a "extract-insights@2.0.0" -m "Release extract-insights hook 2.0.0"
|
||||
git push origin extract-insights@2.0.0
|
||||
```
|
||||
|
||||
**Result**: Two components versioned independently in same repository
|
||||
|
||||
---
|
||||
|
||||
## Scenario 3: Monorepo with Multiple Components (slash-based)
|
||||
|
||||
**Context**: Monorepo with multiple services. Using slash-based namespaces.
|
||||
|
||||
**Recommended Convention**: `component/vX.Y.Z`
|
||||
|
||||
**Steps**:
|
||||
|
||||
```bash
|
||||
# 1. List all hook tags
|
||||
git tag -l "hook/*"
|
||||
# Output:
|
||||
# hook/user-auth/v1.0.0
|
||||
# hook/logging/v0.5.0
|
||||
|
||||
# 2. Check latest logging hook version
|
||||
git tag -l "hook/logging/*" --sort=-v:refname | head -1
|
||||
# Output: hook/logging/v0.5.0
|
||||
|
||||
# 3. Analyze changes (added new feature)
|
||||
git log hook/logging/v0.5.0..HEAD -- src/hooks/logging/
|
||||
|
||||
# 4. Determine version: 0.6.0 (MINOR bump for new feature)
|
||||
|
||||
# 5. Create tag
|
||||
git tag -a "hook/logging/v0.6.0" -m "Release logging hook v0.6.0"
|
||||
|
||||
# 6. Push tag
|
||||
git push origin hook/logging/v0.6.0
|
||||
|
||||
# 7. Set up CI/CD trigger (GitHub Actions)
|
||||
cat << 'EOF' > .github/workflows/deploy-hook.yml
|
||||
name: Deploy Hook
|
||||
on:
|
||||
push:
|
||||
tags:
|
||||
- 'hook/*/v*' # Trigger on any hook tag
|
||||
jobs:
|
||||
deploy:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v3
|
||||
- run: echo "Deploying hook..."
|
||||
EOF
|
||||
```
|
||||
|
||||
**Result**: Logging hook versioned independently, CI/CD configured
|
||||
|
||||
---
|
||||
|
||||
## Scenario 4: Breaking Change Requiring MAJOR Bump
|
||||
|
||||
**Context**: API library with breaking changes (removed deprecated methods).
|
||||
|
||||
**Recommended Convention**: Flat tags (`vX.Y.Z`) for single-component library
|
||||
|
||||
**Steps**:
|
||||
|
||||
```bash
|
||||
# 1. Check current version
|
||||
git tag -l "v*" --sort=-v:refname | head -1
|
||||
# Output: v2.3.5
|
||||
|
||||
# 2. Analyze changes (breaking: removed deprecated auth methods)
|
||||
git log v2.3.5..HEAD --oneline --grep="BREAKING"
|
||||
# Shows commits with breaking changes
|
||||
|
||||
# 3. Determine version: 3.0.0 (MAJOR bump)
|
||||
|
||||
# 4. Create tag
|
||||
git tag -a "v3.0.0" -m "Release v3.0.0 - BREAKING: Removed deprecated auth methods"
|
||||
|
||||
# 5. Push tag
|
||||
git push origin v3.0.0
|
||||
|
||||
# 6. Create GitHub release with migration guide
|
||||
gh release create v3.0.0 \
|
||||
--title "v3.0.0 - Major Release" \
|
||||
--notes "$(cat <<'NOTES'
|
||||
## Breaking Changes
|
||||
|
||||
- Removed deprecated `basicAuth()` method
|
||||
- Replaced with `tokenAuth()` in all examples
|
||||
|
||||
## Migration Guide
|
||||
|
||||
**Before**:
|
||||
```js
|
||||
client.basicAuth(username, password)
|
||||
```
|
||||
|
||||
**After**:
|
||||
```js
|
||||
client.tokenAuth(token)
|
||||
```
|
||||
|
||||
See full migration guide in MIGRATION.md
|
||||
NOTES
|
||||
)"
|
||||
```
|
||||
|
||||
**Result**: Major version bump with clear breaking change communication
|
||||
|
||||
---
|
||||
|
||||
## Scenario 5: Pre-release / Beta Version
|
||||
|
||||
**Context**: Testing new feature before official release.
|
||||
|
||||
**Recommended Convention**: Append pre-release identifier to semver
|
||||
|
||||
**Steps**:
|
||||
|
||||
```bash
|
||||
# 1. Check current stable version
|
||||
git tag -l "v*" --sort=-v:refname | grep -v "beta" | head -1
|
||||
# Output: v1.5.0
|
||||
|
||||
# 2. Create beta tag
|
||||
git tag -a "v1.6.0-beta.1" -m "Release v1.6.0-beta.1 - Testing new dashboard"
|
||||
|
||||
# 3. Push tag
|
||||
git push origin v1.6.0-beta.1
|
||||
|
||||
# 4. Create pre-release on GitHub
|
||||
gh release create v1.6.0-beta.1 \
|
||||
--title "v1.6.0-beta.1 (Pre-release)" \
|
||||
--notes "Beta release for testing new dashboard. Not production-ready." \
|
||||
--prerelease
|
||||
|
||||
# 5. After testing, create stable release
|
||||
git tag -a "v1.6.0" -m "Release v1.6.0 - New dashboard (stable)"
|
||||
git push origin v1.6.0
|
||||
gh release create v1.6.0 \
|
||||
--title "v1.6.0" \
|
||||
--notes "Stable release with new dashboard feature"
|
||||
```
|
||||
|
||||
**Result**: Beta version tested separately from stable releases
|
||||
|
||||
---
|
||||
|
||||
## Scenario 6: Automating Tag Creation from CI/CD
|
||||
|
||||
**Context**: Want to automatically create tags on PR merge to main.
|
||||
|
||||
**Recommended Convention**: Extract version from package.json or VERSION file
|
||||
|
||||
**Steps**:
|
||||
|
||||
```yaml
|
||||
# .github/workflows/auto-tag.yml
|
||||
name: Auto Tag on Merge
|
||||
on:
|
||||
push:
|
||||
branches:
|
||||
- main
|
||||
jobs:
|
||||
tag:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v3
|
||||
with:
|
||||
fetch-depth: 0 # Fetch all tags
|
||||
|
||||
- name: Get version from package.json
|
||||
id: version
|
||||
run: |
|
||||
VERSION=$(jq -r .version package.json)
|
||||
echo "version=v$VERSION" >> $GITHUB_OUTPUT
|
||||
|
||||
- name: Check if tag exists
|
||||
id: check
|
||||
run: |
|
||||
if git rev-parse "${{ steps.version.outputs.version }}" >/dev/null 2>&1; then
|
||||
echo "exists=true" >> $GITHUB_OUTPUT
|
||||
else
|
||||
echo "exists=false" >> $GITHUB_OUTPUT
|
||||
fi
|
||||
|
||||
- name: Create tag
|
||||
if: steps.check.outputs.exists == 'false'
|
||||
run: |
|
||||
git config user.name "GitHub Actions"
|
||||
git config user.email "actions@github.com"
|
||||
git tag -a "${{ steps.version.outputs.version }}" \
|
||||
-m "Release ${{ steps.version.outputs.version }}"
|
||||
git push origin "${{ steps.version.outputs.version }}"
|
||||
|
||||
- name: Create GitHub release
|
||||
if: steps.check.outputs.exists == 'false'
|
||||
env:
|
||||
GH_TOKEN: ${{ github.token }}
|
||||
run: |
|
||||
gh release create "${{ steps.version.outputs.version }}" \
|
||||
--title "${{ steps.version.outputs.version }}" \
|
||||
--generate-notes
|
||||
```
|
||||
|
||||
**Result**: Tags automatically created when version bumped in package.json
|
||||
|
||||
---
|
||||
|
||||
## Scenario 7: Filtering and Listing Tags
|
||||
|
||||
**Context**: Need to find specific tags or latest versions.
|
||||
|
||||
**Commands**:
|
||||
|
||||
```bash
|
||||
# List all tags
|
||||
git tag -l
|
||||
|
||||
# List tags with pattern (marketplace only)
|
||||
git tag -l "marketplace@*"
|
||||
|
||||
# List tags sorted by version (latest first)
|
||||
git tag -l "v*" --sort=-v:refname
|
||||
|
||||
# Get latest marketplace version
|
||||
git tag -l "marketplace@*" --sort=-v:refname | head -1
|
||||
|
||||
# Extract version number only
|
||||
git tag -l "marketplace@*" --sort=-v:refname | head -1 | cut -d'@' -f2
|
||||
|
||||
# List tags with commit messages
|
||||
git tag -l -n1 "v*"
|
||||
|
||||
# Find all tags containing a specific commit
|
||||
git tag --contains abc123
|
||||
|
||||
# List tags created in last week
|
||||
git log --tags --simplify-by-decoration --pretty="format:%ai %d" | grep "tag:" | head -n 7
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Scenario 8: Fixing a Mistake (Deleting and Recreating Tag)
|
||||
|
||||
**Context**: Created tag on wrong commit, need to fix.
|
||||
|
||||
**⚠️ WARNING**: Only do this if tag not yet pushed or used by others!
|
||||
|
||||
**Steps**:
|
||||
|
||||
```bash
|
||||
# 1. Delete local tag
|
||||
git tag -d v1.0.0
|
||||
|
||||
# 2. If already pushed (coordinate with team first!)
|
||||
git push origin :refs/tags/v1.0.0
|
||||
|
||||
# 3. Create tag on correct commit
|
||||
git tag -a v1.0.0 abc123 -m "Release v1.0.0"
|
||||
|
||||
# 4. Push corrected tag
|
||||
git push origin v1.0.0
|
||||
|
||||
# 5. Force-push if needed (DANGEROUS)
|
||||
git push origin v1.0.0 --force
|
||||
```
|
||||
|
||||
**Prevention**: Always verify commit before pushing tags!
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference Commands
|
||||
|
||||
```bash
|
||||
# Create annotated tag
|
||||
git tag -a "v1.0.0" -m "Release v1.0.0"
|
||||
|
||||
# Create tag on specific commit
|
||||
git tag -a "v1.0.0" abc123 -m "Release v1.0.0"
|
||||
|
||||
# Push single tag
|
||||
git push origin v1.0.0
|
||||
|
||||
# Push all tags (use cautiously)
|
||||
git push origin --tags
|
||||
|
||||
# Delete local tag
|
||||
git tag -d v1.0.0
|
||||
|
||||
# Delete remote tag
|
||||
git push origin :refs/tags/v1.0.0
|
||||
|
||||
# List tags sorted
|
||||
git tag -l --sort=-v:refname
|
||||
|
||||
# Show tag details
|
||||
git show v1.0.0
|
||||
|
||||
# Latest tag for pattern
|
||||
git tag -l "marketplace@*" --sort=-v:refname | head -1
|
||||
|
||||
# Create GitHub release from tag
|
||||
gh release create v1.0.0 --title "v1.0.0" --notes "Release notes"
|
||||
```
|
||||
0
skills/semantic-release-tagger/reference/.gitkeep
Normal file
0
skills/semantic-release-tagger/reference/.gitkeep
Normal file
24
skills/semantic-release-tagger/reference/best-practices.md
Normal file
24
skills/semantic-release-tagger/reference/best-practices.md
Normal file
@@ -0,0 +1,24 @@
|
||||
# Best Practices & Important Reminders
|
||||
|
||||
## Core Principles
|
||||
|
||||
- **Start at 0.1.0, not 1.0.0**: Reserve 1.0.0 for production-ready releases
|
||||
- **Consistency is critical**: Pick one tag convention and stick to it across the entire repository
|
||||
- **Tags are immutable**: Once pushed, don't modify or delete tags (users may depend on them)
|
||||
- **Annotated tags preferred**: Use `git tag -a` for all releases (stores metadata)
|
||||
- **Push tags explicitly**: `git push` doesn't push tags automatically, use `git push origin <tagname>`
|
||||
- **Namespace for monorepos**: Even if you have one "main" component, use namespaced tags for future scalability
|
||||
- **Git tags ≠ GitHub releases**: Tags are required, releases are optional but add discoverability
|
||||
- **Fast-forward merges preserve history**: Linear history makes tagging cleaner and more predictable
|
||||
|
||||
## Warnings
|
||||
|
||||
- ⚠️ **Don't mix tag conventions** (e.g., `marketplace/v1.0.0` and `marketplace@2.0.0`)
|
||||
- ⚠️ **Don't skip version numbers** (e.g., 1.0.0 → 1.2.0). Always increment by 1
|
||||
- ⚠️ **Don't delete published tags** without team coordination (breaks dependencies)
|
||||
- ⚠️ **Don't use lightweight tags for releases** (use annotated tags with `-a` flag)
|
||||
|
||||
## Related Skills
|
||||
|
||||
- `release-management` - For changelog generation and deployment
|
||||
- `monorepo-workflow` - For managing multi-component repositories
|
||||
59
skills/semantic-release-tagger/reference/troubleshooting.md
Normal file
59
skills/semantic-release-tagger/reference/troubleshooting.md
Normal file
@@ -0,0 +1,59 @@
|
||||
# Troubleshooting
|
||||
|
||||
## Tag creation fails with "already exists"
|
||||
|
||||
**Symptoms**: `git tag` returns error "tag 'component@1.0.0' already exists"
|
||||
|
||||
**Solution**:
|
||||
1. Check if tag exists: `git tag -l "component@1.0.0"`
|
||||
2. If exists locally but wrong, delete: `git tag -d component@1.0.0`
|
||||
3. If exists remotely, coordinate with team before deleting
|
||||
4. Choose next version number instead (e.g., 1.0.1)
|
||||
|
||||
**Prevention**: Always check latest version before creating tags: `git tag -l "component@*" --sort=-v:refname | head -1`
|
||||
|
||||
---
|
||||
|
||||
## Tag pushed but GitHub release not visible
|
||||
|
||||
**Symptoms**: `git tag` exists but doesn't show in GitHub releases page
|
||||
|
||||
**Solution**:
|
||||
1. Verify tag pushed to remote: `git ls-remote --tags origin | grep component@1.0.0`
|
||||
2. Create GitHub release manually: `gh release create component@1.0.0`
|
||||
3. Or use GitHub web UI: Releases → "Draft a new release" → Choose tag
|
||||
|
||||
**Prevention**: Git tags and GitHub releases are separate. Tags don't automatically create releases.
|
||||
|
||||
---
|
||||
|
||||
## CI/CD not triggering on tag push
|
||||
|
||||
**Symptoms**: Pushed tag but workflow didn't run
|
||||
|
||||
**Solution**:
|
||||
1. Check workflow tag pattern: Does `marketplace@*` match your tag format?
|
||||
2. Verify trigger configured:
|
||||
```yaml
|
||||
on:
|
||||
push:
|
||||
tags:
|
||||
- 'marketplace@*'
|
||||
```
|
||||
3. Test pattern locally: `echo "marketplace@1.0.0" | grep -E "marketplace@.*"`
|
||||
|
||||
**Prevention**: Document and test tag patterns before setting up automation
|
||||
|
||||
---
|
||||
|
||||
## Monorepo tags confusing (which component version?)
|
||||
|
||||
**Symptoms**: Hard to tell which version applies to which component
|
||||
|
||||
**Solution**:
|
||||
1. Always use namespaced tags: `component@X.Y.Z`
|
||||
2. Never use flat tags (`v1.0.0`) in monorepos
|
||||
3. List tags by component: `git tag -l "component@*"`
|
||||
4. Update README with tagging convention
|
||||
|
||||
**Prevention**: Establish and document tag namespace convention early in project
|
||||
@@ -0,0 +1,96 @@
|
||||
# Phase 0: Auto-Context Analysis
|
||||
|
||||
**Purpose**: Gather repository state without user interaction to provide intelligent recommendations.
|
||||
|
||||
**Steps** (execute immediately when skill activates):
|
||||
|
||||
## 1. Detect Repository Structure
|
||||
|
||||
```bash
|
||||
# Check if git repository
|
||||
git rev-parse --git-dir 2>/dev/null
|
||||
|
||||
# List all tags sorted by version
|
||||
git tag -l --sort=-v:refname
|
||||
|
||||
# Count unique tag patterns
|
||||
git tag -l | grep -E '@|/' | wc -l
|
||||
```
|
||||
|
||||
## 2. Identify Existing Convention
|
||||
|
||||
- Parse tag patterns: Look for `@`, `/v`, or flat `v` patterns
|
||||
- Detect most common convention (majority wins)
|
||||
- Flag inconsistencies if multiple patterns found
|
||||
|
||||
Example output:
|
||||
```
|
||||
✅ Detected convention: npm-style @ separator
|
||||
📊 Tags analyzed: 15
|
||||
⚠️ Found inconsistency: 2 tags use /v separator (outdated)
|
||||
```
|
||||
|
||||
## 3. Parse Latest Versions Per Component (if monorepo)
|
||||
|
||||
```bash
|
||||
# For @ convention
|
||||
git tag -l | grep '@' | cut -d'@' -f1 | sort -u
|
||||
|
||||
# For each component, get latest version
|
||||
for component in $(git tag -l | grep '@' | cut -d'@' -f1 | sort -u); do
|
||||
git tag -l "${component}@*" --sort=-v:refname | head -1
|
||||
done
|
||||
```
|
||||
|
||||
## 4. Analyze Commits Since Last Tag
|
||||
|
||||
```bash
|
||||
# Get latest tag for component (or overall)
|
||||
LAST_TAG=$(git tag -l "marketplace@*" --sort=-v:refname | head -1)
|
||||
|
||||
# Get commits since last tag
|
||||
git log ${LAST_TAG}..HEAD --oneline --format="%s"
|
||||
```
|
||||
|
||||
## 5. Classify Changes Using Conventional Commits
|
||||
|
||||
- Parse commit prefixes: `feat:`, `fix:`, `chore:`, `BREAKING CHANGE:`
|
||||
- Determine version bump type:
|
||||
- BREAKING CHANGE or `!` suffix → MAJOR
|
||||
- `feat:` → MINOR
|
||||
- `fix:` or `chore:` → PATCH
|
||||
- Count commits by type for changelog
|
||||
|
||||
## 6. Calculate Recommended Next Version
|
||||
|
||||
```
|
||||
Current: marketplace@1.1.3
|
||||
Commits: 1 chore (README update)
|
||||
Type: PATCH bump
|
||||
Recommended: marketplace@1.1.4
|
||||
```
|
||||
|
||||
## 7. Present Findings to User
|
||||
|
||||
```
|
||||
📦 Repository Analysis:
|
||||
- Convention: @ separator (npm-style)
|
||||
- Latest tag: marketplace@1.1.3
|
||||
- Commits since tag: 1
|
||||
• chore: Update README.md
|
||||
- Change classification: PATCH (documentation only)
|
||||
|
||||
💡 Recommendation: marketplace@1.1.4
|
||||
|
||||
Proceed with tag creation? [Yes/No/Customize]
|
||||
```
|
||||
|
||||
## Output
|
||||
|
||||
Complete repository context analysis with version recommendation.
|
||||
|
||||
## Common Issues
|
||||
|
||||
- **No existing tags**: Recommend starting at `component@0.1.0`
|
||||
- **Mixed conventions**: Warn and recommend migration path
|
||||
- **No conventional commits**: Fall back to user-guided version selection
|
||||
@@ -0,0 +1,67 @@
|
||||
# Phase 1: Choose Tag Naming Convention
|
||||
|
||||
**Purpose**: Select the optimal tag naming pattern based on repository structure and team conventions.
|
||||
|
||||
## Steps
|
||||
|
||||
### 1. Assess Repository Structure
|
||||
|
||||
- Ask: "Is this a monorepo with multiple independently-versioned components?"
|
||||
- Single-component repo: Simpler flat tags work well
|
||||
- Multi-component repo: Namespaced tags provide clarity
|
||||
|
||||
### 2. Understand Existing Conventions
|
||||
|
||||
- Check current tags: `git tag -l`
|
||||
- If tags exist, recommend consistency with current pattern
|
||||
- If no tags exist, choose based on best practices below
|
||||
|
||||
### 3. Choose Namespace Separator (for multi-component repos)
|
||||
|
||||
**Option A: Slash-based namespacing** (`component/vX.Y.Z`)
|
||||
- Pros: Hierarchical, supports git tag filtering (`git tag -l "hook/*"`)
|
||||
- Pros: CI/CD can trigger on patterns (`hook/*` vs `skill/*`)
|
||||
- Cons: Can be confused with directory paths
|
||||
- Example: `marketplace/v1.0.0`, `hook/extract-insights/v2.1.0`
|
||||
|
||||
**Option B: NPM-style @ separator** (`component@X.Y.Z`)
|
||||
- Pros: Familiar to JavaScript developers (`@scope/package@version`)
|
||||
- Pros: Cleaner URLs, semantic clarity, path-safe
|
||||
- Pros: No confusion with directory separators
|
||||
- Cons: Less common in non-JS ecosystems
|
||||
- Note: `v` prefix optional with `@` (separator itself indicates version)
|
||||
- Example: `marketplace@1.0.0`, `extract-insights@2.1.0`
|
||||
|
||||
**Option C: Flat tags with prefixes** (`vX.Y.Z`)
|
||||
- Pros: Simple, universal, works everywhere
|
||||
- Cons: Doesn't scale to multi-component repos
|
||||
- Example: `v1.0.0`, `v2.1.0`
|
||||
|
||||
### 4. Recommend Based on Context
|
||||
|
||||
- **Monorepo with multiple components**: Use Option A or B
|
||||
- **JavaScript/npm ecosystem**: Prefer Option B (`@` separator)
|
||||
- **Single component**: Use Option C (flat `vX.Y.Z`)
|
||||
- **Team familiarity**: If team uses npm daily, choose Option B
|
||||
|
||||
### 5. Document the Decision
|
||||
|
||||
Add tag convention to project README or CONTRIBUTING.md:
|
||||
|
||||
```markdown
|
||||
## Versioning
|
||||
|
||||
We use namespaced semantic versioning with @ separator:
|
||||
- Marketplace: `marketplace@X.Y.Z`
|
||||
- Skills: `skill-name@X.Y.Z`
|
||||
- Hooks: `hook-name@X.Y.Z`
|
||||
```
|
||||
|
||||
## Output
|
||||
|
||||
Chosen tag naming convention documented and agreed upon.
|
||||
|
||||
## Common Issues
|
||||
|
||||
- **Mixing conventions**: Once chosen, stick to one convention
|
||||
- **Forgetting namespace**: In monorepos, always include namespace even for "main" component
|
||||
57
skills/semantic-release-tagger/workflow/phase-2-version.md
Normal file
57
skills/semantic-release-tagger/workflow/phase-2-version.md
Normal file
@@ -0,0 +1,57 @@
|
||||
# Phase 2: Determine Version Number
|
||||
|
||||
**Purpose**: Calculate the correct semantic version number following SemVer rules.
|
||||
|
||||
## Steps
|
||||
|
||||
### 1. Understand Semantic Versioning Format
|
||||
|
||||
`MAJOR.MINOR.PATCH`
|
||||
- **MAJOR**: Breaking changes, incompatible API changes
|
||||
- **MINOR**: New features, backward-compatible additions
|
||||
- **PATCH**: Bug fixes, backward-compatible fixes
|
||||
|
||||
### 2. Identify the Current Version
|
||||
|
||||
- Find latest tag: `git tag -l "component@*" --sort=-v:refname | head -1`
|
||||
- If no tags exist, start at `0.1.0` (not `1.0.0`)
|
||||
- Why `0.1.0`? Signals "initial public release, not production-ready"
|
||||
|
||||
### 3. Analyze Changes Since Last Tag
|
||||
|
||||
- Review commits: `git log <last-tag>..HEAD --oneline`
|
||||
- Check for:
|
||||
- Breaking changes (MAJOR bump)
|
||||
- New features (MINOR bump)
|
||||
- Bug fixes only (PATCH bump)
|
||||
|
||||
### 4. Apply Version Bump Rules
|
||||
|
||||
| Change Type | Current | New Version |
|
||||
|-------------|---------|-------------|
|
||||
| Breaking change | `1.2.3` | `2.0.0` |
|
||||
| New feature | `1.2.3` | `1.3.0` |
|
||||
| Bug fix | `1.2.3` | `1.2.4` |
|
||||
| First release | N/A | `0.1.0` |
|
||||
| Production ready | `0.x.x` | `1.0.0` |
|
||||
|
||||
### 5. Special Version Bump Scenarios
|
||||
|
||||
- **Pre-1.0.0 versions**: Breaking changes still bump MINOR (0.2.0 → 0.3.0)
|
||||
- **Multiple change types**: Use highest severity (feature + bug fix → MINOR)
|
||||
- **No changes**: Don't create a tag (wait for actual changes)
|
||||
|
||||
### 6. Validate Version Number
|
||||
|
||||
- Confirm version doesn't already exist: `git tag -l "component@X.Y.Z"`
|
||||
- Ensure version is higher than latest: `X.Y.Z > current version`
|
||||
|
||||
## Output
|
||||
|
||||
Calculated semantic version number ready for tagging.
|
||||
|
||||
## Common Issues
|
||||
|
||||
- **Starting at 1.0.0**: Reserve for production-ready releases. Use 0.1.0 for initial releases.
|
||||
- **Skipping versions**: Don't skip (e.g., 1.0.0 → 1.2.0). Increment by 1 only.
|
||||
- **Inconsistent component versioning**: Component version ≠ internal script version.
|
||||
@@ -0,0 +1,95 @@
|
||||
# Phase 3: Create Git Tags
|
||||
|
||||
**Purpose**: Execute tag creation commands after user confirmation.
|
||||
|
||||
## Steps
|
||||
|
||||
### 1. Prepare Tag Details
|
||||
|
||||
```
|
||||
Tag name: marketplace@1.1.4
|
||||
Tag message: "Release marketplace 1.1.4"
|
||||
Tag type: Annotated (with metadata)
|
||||
```
|
||||
|
||||
### 2. Show Exact Commands to be Executed
|
||||
|
||||
```bash
|
||||
# Commands that will run:
|
||||
git tag -a "marketplace@1.1.4" -m "Release marketplace 1.1.4"
|
||||
git push origin marketplace@1.1.4
|
||||
```
|
||||
|
||||
### 3. Request User Confirmation
|
||||
|
||||
```
|
||||
Ready to create and push tag marketplace@1.1.4?
|
||||
- This will create an annotated tag on current HEAD
|
||||
- Tag will be pushed to remote origin
|
||||
- Tag cannot be easily modified once pushed
|
||||
|
||||
[Yes, create tag] [No, cancel] [Customize message]
|
||||
```
|
||||
|
||||
### 4. Execute Commands (after user confirms)
|
||||
|
||||
```bash
|
||||
# Create annotated tag
|
||||
git tag -a "marketplace@1.1.4" -m "Release marketplace 1.1.4"
|
||||
|
||||
# Verify tag created
|
||||
git show marketplace@1.1.4 --quiet
|
||||
|
||||
# Push to remote
|
||||
git push origin marketplace@1.1.4
|
||||
```
|
||||
|
||||
### 5. Verify and Report Results
|
||||
|
||||
```bash
|
||||
# Check tag exists locally
|
||||
git tag -l "marketplace@1.1.4"
|
||||
|
||||
# Check tag pushed to remote
|
||||
git ls-remote --tags origin | grep marketplace@1.1.4
|
||||
|
||||
# Show tag details
|
||||
git show marketplace@1.1.4
|
||||
```
|
||||
|
||||
### 6. Present Success Confirmation
|
||||
|
||||
```
|
||||
✅ Tag created successfully!
|
||||
|
||||
Tag: marketplace@1.1.4
|
||||
Commit: abc123de (current HEAD)
|
||||
Pushed to: origin
|
||||
Tagger: Connor <connor@example.com>
|
||||
Date: 2025-11-16 10:51:00
|
||||
|
||||
View on GitHub:
|
||||
https://github.com/user/repo/releases/tag/marketplace@1.1.4
|
||||
|
||||
Next steps:
|
||||
- Create GitHub release? [Yes/No]
|
||||
- Tag another component? [Yes/No]
|
||||
```
|
||||
|
||||
## Output
|
||||
|
||||
Git tag created, pushed to remote, and verified.
|
||||
|
||||
## Automation Features
|
||||
|
||||
- ✅ **Auto-generates tag message** from component name and version
|
||||
- ✅ **Pre-flight checks**: Verifies tag doesn't already exist
|
||||
- ✅ **Atomic execution**: Tag creation + push in sequence
|
||||
- ✅ **Error handling**: Rolls back local tag if push fails
|
||||
- ✅ **Verification**: Confirms tag exists both locally and remotely
|
||||
|
||||
## Common Issues
|
||||
|
||||
- **Tag already exists**: Check before creation, prompt to overwrite or choose new version
|
||||
- **Push fails**: Keep local tag, warn user, offer retry
|
||||
- **Wrong commit**: Ask user to confirm current HEAD before tagging
|
||||
@@ -0,0 +1,114 @@
|
||||
# Phase 4: Create GitHub Release
|
||||
|
||||
**Purpose**: Create user-friendly GitHub release with auto-generated changelog from commits.
|
||||
|
||||
## Steps
|
||||
|
||||
### 1. Check if GitHub CLI is Available
|
||||
|
||||
```bash
|
||||
# Verify gh CLI installed
|
||||
gh --version
|
||||
|
||||
# Check authentication
|
||||
gh auth status
|
||||
```
|
||||
|
||||
### 2. Auto-generate Changelog from Commits
|
||||
|
||||
```bash
|
||||
# Get commits between tags
|
||||
git log marketplace@1.1.3..marketplace@1.1.4 --oneline --format="- %s"
|
||||
|
||||
# Group by conventional commit type
|
||||
# feat: → ### Features
|
||||
# fix: → ### Bug Fixes
|
||||
# chore: → ### Maintenance
|
||||
```
|
||||
|
||||
Example generated changelog:
|
||||
```markdown
|
||||
## What's Changed
|
||||
|
||||
### Maintenance
|
||||
- chore: Update README.md with new examples
|
||||
|
||||
**Full Changelog**: https://github.com/user/repo/compare/marketplace@1.1.3...marketplace@1.1.4
|
||||
```
|
||||
|
||||
### 3. Present Release Preview to User
|
||||
|
||||
```
|
||||
📋 GitHub Release Preview:
|
||||
|
||||
Tag: marketplace@1.1.4
|
||||
Title: "Marketplace v1.1.4"
|
||||
Pre-release: No (version >= 1.0.0)
|
||||
|
||||
Changelog (auto-generated):
|
||||
### Maintenance
|
||||
- chore: Update README.md with new examples
|
||||
|
||||
Create GitHub release now? [Yes/No/Edit changelog]
|
||||
```
|
||||
|
||||
### 4. Execute Release Creation (after confirmation)
|
||||
|
||||
```bash
|
||||
# Determine if pre-release (version < 1.0.0)
|
||||
PRERELEASE_FLAG=""
|
||||
if [[ "1.1.4" =~ ^0\. ]]; then
|
||||
PRERELEASE_FLAG="--prerelease"
|
||||
fi
|
||||
|
||||
# Create release with auto-generated notes
|
||||
gh release create marketplace@1.1.4 \
|
||||
--title "Marketplace v1.1.4" \
|
||||
--notes "$(cat /tmp/changelog.md)" \
|
||||
${PRERELEASE_FLAG}
|
||||
```
|
||||
|
||||
### 5. Verify Release Created
|
||||
|
||||
```bash
|
||||
# Check release exists
|
||||
gh release view marketplace@1.1.4
|
||||
|
||||
# Get release URL
|
||||
gh release view marketplace@1.1.4 --json url -q .url
|
||||
```
|
||||
|
||||
### 6. Present Success Confirmation
|
||||
|
||||
```
|
||||
✅ GitHub Release created successfully!
|
||||
|
||||
Release: marketplace@1.1.4
|
||||
URL: https://github.com/user/repo/releases/tag/marketplace@1.1.4
|
||||
Pre-release: No
|
||||
Published: Yes
|
||||
Notifications: Sent to watchers
|
||||
|
||||
Next steps:
|
||||
- View release on GitHub: [Open URL]
|
||||
- Tag another component? [Yes/No]
|
||||
- Done
|
||||
```
|
||||
|
||||
## Output
|
||||
|
||||
GitHub release published with auto-generated changelog.
|
||||
|
||||
## Automation Features
|
||||
|
||||
- ✅ **Auto-generated changelog**: Parsed from conventional commits
|
||||
- ✅ **Smart pre-release detection**: Versions < 1.0.0 marked as pre-release
|
||||
- ✅ **gh CLI integration**: One-command release creation
|
||||
- ✅ **Changelog grouping**: Commits grouped by type (feat/fix/chore)
|
||||
- ✅ **Full changelog link**: Comparison URL auto-included
|
||||
|
||||
## Common Issues
|
||||
|
||||
- **gh CLI not installed**: Warn user, provide installation instructions, fallback to web UI
|
||||
- **Not authenticated**: Guide user through `gh auth login`
|
||||
- **Empty changelog**: Use default message "Release vX.Y.Z" if no conventional commits
|
||||
@@ -0,0 +1,74 @@
|
||||
# Phase 5: Maintain Tag History
|
||||
|
||||
**Purpose**: Keep tag history clean, organized, and automation-friendly.
|
||||
|
||||
## Steps
|
||||
|
||||
### 1. Filter Tags by Component (monorepos)
|
||||
|
||||
```bash
|
||||
# List all marketplace tags
|
||||
git tag -l "marketplace@*"
|
||||
|
||||
# List all hook tags
|
||||
git tag -l "hook/*"
|
||||
|
||||
# List with sort (latest first)
|
||||
git tag -l "component@*" --sort=-v:refname
|
||||
```
|
||||
|
||||
### 2. Find Latest Version Programmatically
|
||||
|
||||
```bash
|
||||
# Latest marketplace version
|
||||
git tag -l "marketplace@*" --sort=-v:refname | head -1
|
||||
|
||||
# Extract version number only
|
||||
git tag -l "marketplace@*" --sort=-v:refname | head -1 | cut -d'@' -f2
|
||||
```
|
||||
|
||||
### 3. Set Up CI/CD Tag Triggers
|
||||
|
||||
GitHub Actions example:
|
||||
```yaml
|
||||
on:
|
||||
push:
|
||||
tags:
|
||||
- 'marketplace@*' # Trigger on marketplace tags only
|
||||
- 'hook/*' # Trigger on any hook tag
|
||||
```
|
||||
|
||||
### 4. Clean Up Tags (use cautiously)
|
||||
|
||||
```bash
|
||||
# Delete local tag
|
||||
git tag -d old-tag-name
|
||||
|
||||
# Delete remote tag (DANGEROUS - coordinate with team)
|
||||
git push origin :refs/tags/old-tag-name
|
||||
```
|
||||
|
||||
### 5. Fast-forward Merge Awareness
|
||||
|
||||
- When GitHub shows "Fast-forward" on PR merge:
|
||||
- Main branch pointer moved forward without merge commit
|
||||
- Linear history maintained (no divergence)
|
||||
- Happens when PR branch is directly ahead of main
|
||||
- Tags created after fast-forward merge will reference the correct commit
|
||||
|
||||
### 6. Tag Maintenance Best Practices
|
||||
|
||||
- Never modify published tags (immutable release markers)
|
||||
- Document tag conventions in repository
|
||||
- Use automation to enforce tag format
|
||||
- Archive old tags in changelog, don't delete
|
||||
|
||||
## Output
|
||||
|
||||
Clean, organized tag history with automation support.
|
||||
|
||||
## Common Issues
|
||||
|
||||
- **Deleting published tags**: Avoid deleting tags that users may depend on
|
||||
- **Inconsistent tag patterns**: Automation breaks if tags don't follow consistent format
|
||||
- **Missing tag documentation**: Always document your tagging convention in README
|
||||
Reference in New Issue
Block a user