Skip to content

Commit 9cf1114

Browse files
endersonmenezesendersonmenezes
committed
feat: add release-manager skill for managing semantic version releases and updating major version alias
1 parent dcf58cd commit 9cf1114

File tree

3 files changed

+172
-0
lines changed

3 files changed

+172
-0
lines changed

‎.github/agents/disk-space-engineer.agent.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -73,6 +73,7 @@ For deep technical details not in copilot-instructions, read these on-demand:
7373
Load skills from `.github/skills/` for specialized tasks:
7474

7575
- **changelog-maintainer**: Analyze git changes and maintain CHANGELOG entries following Keep a Changelog format
76+
- **release-manager**: Create new semantic version releases and update the major version alias tag using `gh` CLI
7677

7778
## Do's and Don'ts
7879

‎.github/skills/release-manager/SKILL.md‎

Lines changed: 170 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,170 @@
1+
# Skill: Release Manager
2+
3+
## Description
4+
5+
Manages the full release cycle for the Free Disk Space GitHub Action using `gh` CLI. Creates a new semantic version release and updates the major version alias tag so users pinning to `vMAJOR` always get the latest.
6+
7+
## Prerequisites
8+
9+
- `gh` CLI installed and authenticated (`gh auth status` must succeed)
10+
- User must have push + release permissions on the repository
11+
- Working directory must be the repository root
12+
13+
## When to Use
14+
15+
Trigger this skill when:
16+
- User asks to "create a release", "publish a release", or "cut a release"
17+
- User mentions "update major tag", "bump version", or "new version"
18+
- User wants to "prepare vX.Y.Z for release"
19+
20+
## IMPORTANT: Always Confirm the Target Version
21+
22+
Before proceeding, **always confirm the new version with the user** unless they explicitly stated it. Use the `vscode/askQuestions` tool:
23+
24+
```json
25+
{
26+
"questions": [
27+
{
28+
"header": "Release Version",
29+
"question": "Current latest tag is `<detected_tag>`. What version should the new release be?",
30+
"options": [
31+
{ "label": "<next_patch>", "description": "Patch bump" },
32+
{ "label": "<next_minor>", "description": "Minor bump" },
33+
{ "label": "<next_major>", "description": "Major bump" }
34+
],
35+
"allowFreeformInput": true
36+
}
37+
]
38+
}
39+
```
40+
41+
If the user already specified the version (e.g., "release v3.2.0"), skip the prompt and proceed.
42+
43+
## Workflow
44+
45+
### 1. Detect Current State
46+
47+
```bash
48+
# Verify gh is authenticated
49+
gh auth status
50+
51+
# Get the latest semantic version tag (exclude major-only tags like v3)
52+
git tag --sort=-v:refname | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+$' | head -1
53+
54+
# Get the current major version
55+
# e.g., v3.1.0 → MAJOR=3
56+
```
57+
58+
### 2. Confirm the Changelog is Ready
59+
60+
Before creating any release, verify that `CHANGELOG.md` has an entry for the target version. If the `[Unreleased]` section has content but no version entry exists, invoke the **changelog-maintainer** skill first to finalize the entry.
61+
62+
### 3. Create the New Semantic Version Release
63+
64+
```bash
65+
# Set variables
66+
NEW_VERSION="v3.2.0" # example — use the confirmed version
67+
68+
# Create the release (this also creates the tag)
69+
gh release create "${NEW_VERSION}" \
70+
--title "${NEW_VERSION}" \
71+
--notes-file - <<< "$(extract_changelog_notes)"
72+
--target main
73+
```
74+
75+
**For the release notes:** Extract the relevant section from `CHANGELOG.md` for this version. If no changelog entry exists, use `--generate-notes` to auto-generate from commits.
76+
77+
Practical approach:
78+
```bash
79+
# Option A: Use changelog entry (preferred)
80+
# Extract the section between the version header and the next header
81+
# and pass it as release notes
82+
83+
# Option B: Auto-generate from commits (fallback)
84+
gh release create "${NEW_VERSION}" \
85+
--title "${NEW_VERSION}" \
86+
--generate-notes \
87+
--target main
88+
```
89+
90+
### 4. Update the Major Version Alias
91+
92+
GitHub Actions users pin to `vMAJOR` (e.g., `uses: endersonmenezes/free-disk-space@v3`). After creating the new release, the major tag must be moved to point to the same commit.
93+
94+
**This requires deleting and recreating both the release and the tag for the major version.**
95+
96+
```bash
97+
MAJOR_VERSION="v3" # extract from NEW_VERSION
98+
99+
# Step 4a: Delete the existing major release (if it exists)
100+
gh release delete "${MAJOR_VERSION}" --yes || true
101+
102+
# Step 4b: Delete the existing major tag (remote + local)
103+
git push origin --delete "${MAJOR_VERSION}" || true
104+
git tag -d "${MAJOR_VERSION}" || true
105+
106+
# Step 4c: Create the new major tag pointing to HEAD
107+
git tag "${MAJOR_VERSION}"
108+
git push origin "${MAJOR_VERSION}"
109+
110+
# Step 4d: Detect the repo slug and create the new major release
111+
REPO_SLUG=$(gh repo view --json nameWithOwner -q '.nameWithOwner')
112+
113+
gh release create "${MAJOR_VERSION}" \
114+
--title "${MAJOR_VERSION}" \
115+
--notes "Alias to [${NEW_VERSION}](https://github.com/${REPO_SLUG}/releases/tag/${NEW_VERSION})" \
116+
--target main
117+
```
118+
119+
### 5. Verify
120+
121+
```bash
122+
# List the latest releases to confirm
123+
gh release list --limit 5
124+
125+
# Verify tags point to the same commit
126+
git log --oneline -1 "${NEW_VERSION}"
127+
git log --oneline -1 "${MAJOR_VERSION}"
128+
```
129+
130+
Both tags must resolve to the same commit SHA.
131+
132+
## Complete Example (v3.1.0 → v3.2.0)
133+
134+
```bash
135+
# 1. Create the new release
136+
gh release create v3.2.0 --title "v3.2.0" --generate-notes --target main
137+
138+
# 2. Delete old major alias
139+
gh release delete v3 --yes
140+
git push origin --delete v3
141+
git tag -d v3
142+
143+
# 3. Recreate major alias
144+
git tag v3
145+
git push origin v3
146+
REPO_SLUG=$(gh repo view --json nameWithOwner -q '.nameWithOwner')
147+
gh release create v3 --title "v3" --notes "Alias to [v3.2.0](https://github.com/${REPO_SLUG}/releases/tag/v3.2.0)" --target main
148+
149+
# 4. Verify
150+
gh release list --limit 5
151+
```
152+
153+
## Error Handling
154+
155+
| Error | Cause | Fix |
156+
|-------|-------|-----|
157+
| `gh: Not logged in` | gh CLI not authenticated | Run `gh auth login` first |
158+
| `release not found` on delete | Major release doesn't exist yet (first release) | Safe to ignore (`\|\| true`) |
159+
| `tag not found` on delete | Major tag doesn't exist yet | Safe to ignore (`\|\| true`) |
160+
| `already exists` on create | Tag/release wasn't deleted properly | Delete manually, retry |
161+
| `permission denied` | Missing repo permissions | User must have write access |
162+
163+
## Rules
164+
165+
- **NEVER** create a release without confirming the version with the user (unless explicitly provided)
166+
- **ALWAYS** verify `gh auth status` before running any `gh` command
167+
- **ALWAYS** delete the major release BEFORE deleting the major tag
168+
- **ALWAYS** create the major tag BEFORE creating the major release
169+
- **NEVER** use `--force` on tag push — delete and recreate instead
170+
- The major release notes are always: `Alias to [<NEW_VERSION>](https://github.com/<OWNER>/<REPO>/releases/tag/<NEW_VERSION>)` (with link to the release)

‎AGENTS.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@ Deep technical reference for contributors and AI agents. For coding conventions,
99
| `.github/copilot-instructions.md` | Project conventions, coding standards, testing strategy (always loaded) |
1010
| `.github/agents/disk-space-engineer.agent.md` | Custom agent: workflows, behavioral rules, task feedback |
1111
| `.github/skills/changelog-maintainer/SKILL.md` | Skill for maintaining changelog entries |
12+
| `.github/skills/release-manager/SKILL.md` | Skill for creating releases and updating major version alias tag |
1213

1314
> **Note**: `copilot-instructions.md` is the canonical source for code conventions, function patterns, ShellCheck, commit messages, testing matrix, and versioning. This file contains only supplementary technical details not covered there.
1415

0 commit comments

Comments
 (0)