Skip to content

Commit df9dab1

Browse files
emcdemcd
committed
Update project from Copier template (v1.27).
1 parent 53c3128 commit df9dab1

16 files changed

Lines changed: 641 additions & 65 deletions

‎.auxiliary/configuration/claude/.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
settings.local.json

‎.auxiliary/configuration/claude/commands/release-final.md‎

Lines changed: 173 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,173 @@
1+
---
2+
allowed-tools: Bash(git status), Bash(git pull:*), Bash(git checkout:*), Bash(git add:*), Bash(git commit:*), Bash(git tag:*), Bash(git rm:*), Bash(git cherry-pick:*), Bash(git log:*), Bash(git branch:*), Bash(gh run list:*), Bash(gh run watch:*), Bash(hatch version:*), Bash(hatch --env develop run:*), Bash(echo:*), Bash(ls:*), Bash(grep:*), LS, Read
3+
description: Execute automated final release with QA monitoring and development cycle setup
4+
---
5+
6+
# Release Final
7+
8+
**NOTE: This is an experimental workflow! If anything seems unclear or missing,
9+
please stop for consultation with the user.**
10+
11+
For execution of a fully-automated final release.
12+
13+
Below is a validated process to create a final release with automated
14+
monitoring and next development cycle setup.
15+
16+
Target release version: `$ARGUMENTS` (e.g., `1.6`, `2.0`)
17+
18+
**CRITICAL**: Verify exactly one target release version provided.
19+
**HALT if**:
20+
- No target release version is provided
21+
- Multiple release versions provided (e.g., `1.6 foo bar`)
22+
- Release version format doesn't match `X.Y` pattern (e.g., `1.6.2`, `1.6a0`)
23+
24+
## Context
25+
26+
- Current git status: !`git status`
27+
- Current branch: !`git branch --show-current`
28+
- Current version: !`hatch version`
29+
- Recent commits: !`git log --oneline -10`
30+
- Available towncrier fragments: !`ls .auxiliary/data/towncrier/*.rst 2>/dev/null || echo "No fragments found"`
31+
- Target release branch status: !`git branch -r | grep release-$ARGUMENTS || echo "Release branch not found - will create new"`
32+
- Local release branch status: !`git branch | grep release-$ARGUMENTS || echo "No local release branch"`
33+
34+
## Prerequisites
35+
36+
Before starting, ensure:
37+
- GitHub CLI (`gh`) is installed and authenticated
38+
- For new releases: All changes are committed to `master` branch
39+
- For existing release branches: Release candidate has been validated and tested
40+
- Working directory is clean with no uncommitted changes
41+
- Towncrier news fragments are present for the release enhancements
42+
43+
## Process Summary
44+
45+
Key functional areas of the process:
46+
47+
1. **Branch Setup**: Create new release branch or checkout existing one
48+
2. **Version Bump**: Set version to final release (major/minor/patch as appropriate)
49+
3. **Update Changelog**: Run Towncrier to build final changelog
50+
4. **QA Monitoring**: Push commits and monitor QA workflow with GitHub CLI
51+
5. **Tag Release**: Create signed git tag after QA passes
52+
6. **Release Monitoring**: Monitor release workflow deployment
53+
7. **Cleanup**: Remove news fragments and cherry-pick back to master
54+
8. **Next Development Cycle**: Set up master branch for next development version
55+
56+
## Safety Requirements
57+
58+
**CRITICAL**: You MUST halt the process and consult with the user if ANY of the
59+
following occur:
60+
61+
- **Step failures**: If any command fails, git operation errors, or tests fail
62+
- **Workflow failures**: If QA or release workflows show failed jobs
63+
- **Unexpected output**: If commands produce unclear or concerning results
64+
- **Version conflicts**: If version bumps don't match expected patterns
65+
- **Network issues**: If GitHub operations timeout or fail repeatedly
66+
67+
**Your responsibilities**:
68+
- Validate each step succeeds before proceeding to the next
69+
- Monitor workflow status and halt on any failures
70+
- Provide clear progress updates throughout the process
71+
- Maintain clean git hygiene and proper branching
72+
- Use your judgment to assess when manual intervention is needed
73+
74+
## Release Process
75+
76+
Execute the following steps for target version `$ARGUMENTS`:
77+
78+
### 1. Pre-Release Quality Check
79+
Run local quality assurance to catch issues early:
80+
```bash
81+
git status && git pull origin master
82+
hatch --env develop run linters
83+
hatch --env develop run testers
84+
hatch --env develop run docsgen
85+
```
86+
87+
### 2. Release Branch Setup
88+
Determine release branch name from target version (e.g., `1.6` → `release-1.6`).
89+
90+
**If release branch exists** (for RC→final conversion):
91+
```bash
92+
git checkout release-$ARGUMENTS
93+
git pull origin release-$ARGUMENTS
94+
```
95+
96+
**If creating new release branch**:
97+
```bash
98+
git checkout master && git pull origin master
99+
git checkout -b release-$ARGUMENTS
100+
```
101+
102+
### 3. Version Management
103+
Set version to target release version:
104+
```bash
105+
hatch version $ARGUMENTS
106+
git commit -am "Version: $(hatch version)"
107+
```
108+
109+
### 4. Changelog Generation
110+
```bash
111+
hatch --env develop run towncrier build --keep --version $(hatch version)
112+
git commit -am "Update changelog for v$(hatch version) release."
113+
```
114+
115+
### 5. Quality Assurance Phase
116+
Push branch and monitor QA workflow:
117+
```bash
118+
# Use -u flag for new branches, omit for existing
119+
git push [-u] origin release-$ARGUMENTS
120+
121+
# Monitor QA workflow - get run ID from output
122+
gh run list --workflow=qa --limit=1
123+
gh run watch <qa-run-id> --interval 30 --compact
124+
```
125+
**CRITICAL - DO NOT PROCEED UNTIL WORKFLOW COMPLETES:**
126+
- Monitor QA workflow with `gh run watch`
127+
- Use `timeout: 300000` (5 minutes) parameter in Bash tool for monitoring commands
128+
- If command times out, immediately rerun `gh run watch` until completion
129+
- Only proceed to next step after seeing "✓ [workflow-name] completed with 'success'"
130+
- HALT if any jobs fail - consult user before proceeding
131+
132+
### 6. Release Deployment
133+
**Verify QA passed before proceeding to release tag:**
134+
```bash
135+
git tag -m "Release v$(hatch version): <brief-description>." v$(hatch version)
136+
git push --tags
137+
138+
gh run list --workflow=release --limit=1
139+
gh run watch <release-run-id> --interval 30 --compact
140+
```
141+
**CRITICAL - DO NOT PROCEED UNTIL WORKFLOW COMPLETES:**
142+
- Monitor release workflow with `gh run watch`
143+
- Use `timeout: 600000` (10 minutes) parameter in Bash tool for monitoring commands
144+
- If command times out, immediately rerun `gh run watch` until completion
145+
- Only proceed to next step after seeing "✓ [workflow-name] completed with 'success'"
146+
- HALT if any jobs fail - consult user before proceeding
147+
148+
### 7. Post-Release Cleanup
149+
```bash
150+
git rm .auxiliary/data/towncrier/*.rst
151+
git commit -m "Clean up news fragments."
152+
git push origin release-$ARGUMENTS
153+
```
154+
155+
### 8. Master Branch Integration
156+
Cherry-pick release commits back to master:
157+
```bash
158+
git checkout master && git pull origin master
159+
git cherry-pick <changelog-commit-hash>
160+
git cherry-pick <cleanup-commit-hash>
161+
git push origin master
162+
```
163+
164+
### 9. Next Development Cycle (Major/Minor Releases Only)
165+
Set up next development version:
166+
```bash
167+
hatch version minor,alpha
168+
git commit -am "Version: $(hatch version)"
169+
git tag -m "Start development for v$(hatch version | sed 's/a[0-9]*$//')." i$(hatch version | sed 's/a[0-9]*$//')
170+
git push origin master --tags
171+
```
172+
173+
**Note**: Use `git log --oneline` to identify commit hashes for cherry-picking.

‎.auxiliary/configuration/claude/commands/release-patch.md‎

Lines changed: 207 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,207 @@
1+
---
2+
allowed-tools: Bash(git status), Bash(git pull:*), Bash(git checkout:*), Bash(git commit:*), Bash(git tag:*), Bash(git rm:*), Bash(git cherry-pick:*), Bash(git log:*), Bash(git branch:*), Bash(gh run list:*), Bash(gh run watch:*), Bash(hatch version:*), Bash(hatch --env develop run:*), Bash(echo:*), Bash(ls:*), Bash(grep:*), LS, Read
3+
description: Execute automated patch release with QA monitoring and master integration
4+
---
5+
6+
# Release Patch
7+
8+
**NOTE: This is an experimental workflow! If anything seems unclear or missing,
9+
please stop for consultation with the user.**
10+
11+
For execution of a fully-automated postrelease patch.
12+
13+
Below is a validated process to create patch releases with automated monitoring
14+
and clean integration back to master.
15+
16+
Target release version: `$ARGUMENTS` (e.g., `1.24`, `2.3`)
17+
18+
**CRITICAL**: Verify exactly one target release version provided.
19+
**HALT if**:
20+
- No target release version is provided
21+
- Multiple release versions provided (e.g., `1.6 foo bar`)
22+
- Release version format doesn't match `X.Y` pattern (e.g., `1.6.2`, `1.6a0`)
23+
24+
## Context
25+
26+
- Current git status: !`git status`
27+
- Current branch: !`git branch --show-current`
28+
- Current version: !`hatch version`
29+
- Recent commits: !`git log --oneline -10`
30+
- Available towncrier fragments: !`ls .auxiliary/data/towncrier/*.rst 2>/dev/null || echo "No fragments found"`
31+
- Target release branch status: !`git branch -r | grep release-$ARGUMENTS || echo "Release branch not found"`
32+
33+
## Prerequisites
34+
35+
Before running this command, ensure:
36+
- GitHub CLI (`gh`) is installed and authenticated
37+
- Release branch exists for the target version (e.g., `release-1.24` for version `1.24`)
38+
- Working directory is clean with no uncommitted changes
39+
- Towncrier news fragments are present for the patch changes
40+
41+
## Process Summary
42+
43+
Key functional areas of the process:
44+
45+
1. **Branch Setup**: Checkout and update the appropriate release branch
46+
2. **Version Bump**: Increment to next patch version with `hatch version patch`
47+
3. **Update Changelog**: Run Towncrier to build patch changelog
48+
4. **QA Monitoring**: Push commits and monitor QA workflow with GitHub CLI
49+
5. **Tag Release**: Create signed git tag after QA passes
50+
6. **Release Monitoring**: Monitor release workflow deployment
51+
7. **Cleanup**: Remove news fragments and cherry-pick back to master
52+
53+
## Safety Requirements
54+
55+
**CRITICAL**: You MUST halt the process and consult with the user if ANY of the following occur:
56+
57+
- **Step failures**: If any command fails, git operation errors, or tests fail
58+
- **Workflow failures**: If QA or release workflows show failed jobs
59+
- **Version conflicts**: If patch version doesn't match expected patterns
60+
- **Branch issues**: If release branch doesn't exist or is in unexpected state
61+
- **Network issues**: If GitHub operations timeout or fail repeatedly
62+
63+
**Your responsibilities**:
64+
- Validate each step succeeds before proceeding to the next
65+
- Monitor workflow status and halt on any failures
66+
- Provide clear progress updates throughout the process
67+
- Maintain clean git hygiene and proper branching
68+
- Use your judgment to assess when manual intervention is needed
69+
70+
## Release Process
71+
72+
Execute the following steps for target release version `$ARGUMENTS`:
73+
74+
### 1. Pre-Release Quality Check
75+
Run local quality assurance to catch issues early:
76+
```bash
77+
git status && git pull origin master
78+
hatch --env develop run linters
79+
hatch --env develop run testers
80+
hatch --env develop run docsgen
81+
```
82+
83+
### 2. Release Branch Setup
84+
Checkout the target release branch:
85+
```bash
86+
git checkout release-$ARGUMENTS
87+
git pull origin release-$ARGUMENTS
88+
```
89+
90+
### 3. Patch Integration
91+
**Determine patch location and integrate if needed:**
92+
93+
### 3.1. Identify Patch Commits
94+
Before cherry-picking, identify which commits contain actual patch fixes vs. maintenance:
95+
96+
```bash
97+
git log --oneline master
98+
git log --graph --oneline master --since="1 month ago"
99+
# Show commits on master not on release branch
100+
git log --oneline release-$ARGUMENTS..master --since="1 month ago"
101+
```
102+
103+
**Patch commits** (always cherry-pick):
104+
- Bug fixes
105+
- Security patches
106+
- Critical functionality fixes
107+
108+
**Maintenance commits** (evaluate case-by-case):
109+
- Template updates
110+
- Dependency bumps
111+
- Documentation changes
112+
113+
Use `git show <commit>` to review each commit's content before deciding.
114+
115+
**If patches were developed on master** (cherry-pick to release branch):
116+
```bash
117+
# Cherry-pick patch commits from master to release branch
118+
# Use git log --oneline master to identify relevant commit hashes
119+
git cherry-pick <patch-commit-hash-1>
120+
git cherry-pick <patch-commit-hash-2>
121+
# Repeat for all patch commits
122+
```
123+
124+
**If patches were developed on release branch**: Skip this step - patches are already present.
125+
126+
### 4. Pre-Release Validation
127+
Run linting to catch issues before formal release process:
128+
```bash
129+
hatch --env develop run linters
130+
```
131+
**HALT if any linting errors** - fix issues before proceeding.
132+
133+
### 5. Version Management
134+
Increment to next patch version:
135+
```bash
136+
hatch version patch
137+
git commit -am "Version: $(hatch version)"
138+
```
139+
140+
### 6. Changelog Generation
141+
```bash
142+
hatch --env develop run towncrier build --keep --version $(hatch version)
143+
git commit -am "Update changelog for v$(hatch version) patch release."
144+
```
145+
146+
### 7. Quality Assurance Phase
147+
Push branch and monitor QA workflow:
148+
```bash
149+
git push origin release-$ARGUMENTS
150+
151+
# Monitor QA workflow - get run ID from output
152+
gh run list --workflow=qa --limit=1
153+
gh run watch <qa-run-id> --interval 30 --compact
154+
```
155+
**CRITICAL - DO NOT PROCEED UNTIL WORKFLOW COMPLETES:**
156+
- Monitor QA workflow with `gh run watch`
157+
- Use `timeout: 300000` (5 minutes) parameter in Bash tool for monitoring commands
158+
- If command times out, immediately rerun `gh run watch` until completion
159+
- Only proceed to next step after seeing "✓ [workflow-name] completed with 'success'"
160+
- HALT if any jobs fail - consult user before proceeding
161+
162+
### 8. Release Deployment
163+
**Verify QA passed before proceeding to release tag:**
164+
```bash
165+
git tag -m "Release v$(hatch version) patch: <brief-description>." v$(hatch version)
166+
git push --tags
167+
168+
gh run list --workflow=release --limit=1
169+
gh run watch <release-run-id> --interval 30 --compact
170+
```
171+
**CRITICAL - DO NOT PROCEED UNTIL WORKFLOW COMPLETES:**
172+
- Monitor release workflow with `gh run watch`
173+
- Use `timeout: 600000` (10 minutes) parameter in Bash tool for monitoring commands
174+
- If command times out, immediately rerun `gh run watch` until completion
175+
- Only proceed to next step after seeing "✓ [workflow-name] completed with 'success'"
176+
- HALT if any jobs fail - consult user before proceeding
177+
178+
### 9. Post-Release Cleanup
179+
```bash
180+
git rm .auxiliary/data/towncrier/*.rst
181+
git commit -m "Clean up news fragments."
182+
git push origin release-$ARGUMENTS
183+
```
184+
185+
### 10. Master Branch Integration
186+
Cherry-pick commits back to master based on patch development location:
187+
188+
**If patches were developed on master**: Cherry-pick changelog and cleanup commits:
189+
```bash
190+
git checkout master && git pull origin master
191+
git cherry-pick <changelog-commit-hash>
192+
git cherry-pick <cleanup-commit-hash>
193+
git push origin master
194+
```
195+
196+
**If patches were developed on release branch**: Cherry-pick patch, changelog, and cleanup commits:
197+
```bash
198+
git checkout master && git pull origin master
199+
git cherry-pick <patch-commit-hash-1>
200+
git cherry-pick <patch-commit-hash-2>
201+
# Repeat for all patch commits
202+
git cherry-pick <changelog-commit-hash>
203+
git cherry-pick <cleanup-commit-hash>
204+
git push origin master
205+
```
206+
207+
**Note**: Use `git log --oneline` to identify commit hashes for cherry-picking.

0 commit comments

Comments
 (0)