Skip to content

Commit a8a5cf2

Browse files
jrollinjrollin
committed
chore: add release automation script and documentation
1 parent 3532f43 commit a8a5cf2

File tree

4 files changed

+225
-5
lines changed

4 files changed

+225
-5
lines changed

‎CLAUDE.md‎

Lines changed: 17 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -91,10 +91,9 @@ cargo fmt # Code formatting
9191
# Release
9292
cargo build --release # Optimized build
9393

94-
# CI/CD
95-
git cliff --latest # Preview changelog for next release
96-
git tag v0.2.0 # Create version tag (triggers release workflow)
97-
git push origin v0.2.0 # Push tag to trigger automated release
94+
# Release (use automated script)
95+
./scripts/release.sh 0.8.0 # Bumps version, updates changelog, creates tag
96+
git push origin main && git push origin v0.8.0 # Push to trigger automated release workflow
9897
```
9998

10099
## CI/CD Workflows
@@ -110,9 +109,22 @@ Triggers on git tag `v*.*.*`:
110109

111110
**Creating a Release:**
112111
```bash
113-
git tag v0.2.0 && git push origin v0.2.0
112+
# Use the automated release script
113+
./scripts/release.sh 0.8.0
114+
115+
# Then push to trigger the release workflow
116+
git push origin main && git push origin v0.8.0
114117
```
115118

119+
The script handles:
120+
- Version validation and duplicate tag checking
121+
- Cargo.toml and Cargo.lock updates
122+
- Complete CHANGELOG.md regeneration
123+
- Commit with conventional message
124+
- Tag creation
125+
126+
See [docs/steering/release-process.md](docs/steering/release-process.md) for detailed instructions.
127+
116128
See `.github/workflows/` for complete workflow details.
117129

118130
## Project Structure

‎docs/README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@
1111
- 📋 **Features**: [Features Overview](#features-overview) below
1212
- 🏗️ **Architecture**: [docs/steering/structure.md](steering/structure.md)
1313
- 🛠️ **Tech Stack**: [docs/steering/tech.md](steering/tech.md)
14+
- 🚀 **Releases**: [docs/steering/release-process.md](steering/release-process.md)
1415

1516
## Documentation Structure
1617

‎docs/steering/release-process.md‎

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
# Release Process
2+
3+
## Standard Release Workflow
4+
5+
### Prerequisites
6+
- Clean working directory (no uncommitted changes)
7+
- All tests passing on main: `cargo test`
8+
- Version number decided (following semver)
9+
- `git-cliff` installed: `cargo install git-cliff` (script can auto-install)
10+
11+
### Steps
12+
13+
1. **Run the release script**:
14+
```bash
15+
./scripts/release.sh 0.8.0
16+
```
17+
18+
2. **Review the changes**:
19+
- Script shows modified files (Cargo.toml, Cargo.lock, CHANGELOG.md)
20+
- Commit created with message: `chore(release): bump version to 0.8.0`
21+
- Tag created: `v0.8.0`
22+
23+
3. **Push to trigger release**:
24+
```bash
25+
git push origin main && git push origin v0.8.0
26+
```
27+
28+
4. **Verify release**:
29+
- Check GitHub Actions for release workflow
30+
- Verify binaries built successfully
31+
- Confirm GitHub Release published
32+
33+
### What the Script Does
34+
35+
1. ✓ Validates version format (X.Y.Z)
36+
2. ✓ Checks tag doesn't already exist
37+
3. ✓ Verifies working directory is clean
38+
4. ✓ Updates Cargo.toml version (`cargo set-version`)
39+
5. ✓ Updates Cargo.lock (`cargo check`)
40+
6. ✓ Regenerates complete CHANGELOG.md (`git cliff`)
41+
7. ✓ Shows diff of changes
42+
8. ✓ Commits with conventional message
43+
9. ✓ Creates annotated tag
44+
10. ✓ Prompts you to push
45+
46+
### Rollback Procedure
47+
48+
If you need to undo a release before pushing:
49+
50+
```bash
51+
# Delete tag locally
52+
git tag -d v0.8.0
53+
54+
# Undo commit
55+
git reset --hard HEAD~1
56+
```
57+
58+
If you already pushed:
59+
60+
```bash
61+
# Delete remote tag
62+
git push origin :v0.8.0
63+
64+
# Revert commit on main
65+
git revert HEAD
66+
git push origin main
67+
```
68+
69+
## Manual Release (Not Recommended)
70+
71+
If you skip the script and push a tag directly:
72+
73+
```bash
74+
git tag v0.8.0
75+
git push origin v0.8.0
76+
```
77+
78+
**Warning**: This creates a release but leaves Cargo.toml and CHANGELOG.md out of sync with the tag version.
79+
80+
## Troubleshooting
81+
82+
### "Version must be in semver format"
83+
- Use X.Y.Z format (e.g., 0.8.0, 1.0.0, 2.1.3)
84+
- Don't include 'v' prefix
85+
- Example: `./scripts/release.sh 0.8.0` ✓
86+
- Not: `./scripts/release.sh v0.8.0` ✗
87+
88+
### "Tag already exists"
89+
- Check existing tags: `git tag --list | tail -10`
90+
- Use next version number
91+
- To delete existing tag: `git tag -d v0.8.0`
92+
93+
### "You have uncommitted changes"
94+
- Commit or stash your changes first
95+
- Ensure clean working directory: `git status`
96+
97+
### "git-cliff not found"
98+
- Install: `cargo install git-cliff`
99+
- Or let script auto-install (first run takes longer)
100+
101+
### Release workflow doesn't trigger after push
102+
- Verify tag pushed: `git ls-remote --tags origin | grep v0.8.0`
103+
- Check release.yml exists in `.github/workflows/`
104+
- Check Actions tab for errors

‎scripts/release.sh‎

Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
1+
#!/bin/bash
2+
set -e
3+
4+
# Colors for output
5+
RED='\033[0;31m'
6+
GREEN='\033[0;32m'
7+
YELLOW='\033[1;33m'
8+
NC='\033[0m' # No Color
9+
10+
# Check if version argument provided
11+
if [ -z "$1" ]; then
12+
echo -e "${RED}Error: Version number required${NC}"
13+
echo "Usage: $0 <version>"
14+
echo "Example: $0 0.8.0"
15+
exit 1
16+
fi
17+
18+
VERSION=$1
19+
20+
# Validate version format (semver: X.Y.Z)
21+
if ! echo "$VERSION" | grep -E '^[0-9]+\.[0-9]+\.[0-9]+$' > /dev/null; then
22+
echo -e "${RED}Error: Version must be in semver format (X.Y.Z)${NC}"
23+
echo "Example: 0.8.0, 1.0.0, 2.1.3"
24+
echo "Received: $VERSION"
25+
exit 1
26+
fi
27+
28+
echo -e "${GREEN}✓${NC} Version format valid: $VERSION"
29+
30+
# Check if tag already exists
31+
if git rev-parse "v$VERSION" >/dev/null 2>&1; then
32+
echo -e "${RED}Error: Tag v$VERSION already exists${NC}"
33+
echo "Existing tags:"
34+
git tag --list | tail -10
35+
exit 1
36+
fi
37+
38+
echo -e "${GREEN}✓${NC} Tag v$VERSION does not exist"
39+
40+
# Check if working directory is clean
41+
if ! git diff-index --quiet HEAD --; then
42+
echo -e "${YELLOW}Warning: You have uncommitted changes${NC}"
43+
echo "Please commit or stash your changes first"
44+
exit 1
45+
fi
46+
47+
echo -e "${GREEN}✓${NC} Working directory is clean"
48+
49+
# Check required tools
50+
if ! command -v cargo &> /dev/null; then
51+
echo -e "${RED}Error: cargo not found${NC}"
52+
exit 1
53+
fi
54+
55+
if ! command -v git-cliff &> /dev/null; then
56+
echo -e "${YELLOW}git-cliff not found, installing...${NC}"
57+
cargo install git-cliff
58+
fi
59+
60+
echo ""
61+
echo "Updating version to $VERSION..."
62+
echo ""
63+
64+
# Update Cargo.toml version
65+
echo "→ Updating Cargo.toml"
66+
cargo set-version "$VERSION"
67+
68+
# Update Cargo.lock
69+
echo "→ Updating Cargo.lock"
70+
cargo check --quiet
71+
72+
# Generate CHANGELOG.md
73+
echo "→ Generating CHANGELOG.md"
74+
git cliff -o CHANGELOG.md
75+
76+
# Show what changed
77+
echo ""
78+
echo "Files modified:"
79+
git diff --stat Cargo.toml Cargo.lock CHANGELOG.md
80+
81+
# Commit changes
82+
echo ""
83+
echo "→ Committing changes"
84+
git add Cargo.toml Cargo.lock CHANGELOG.md
85+
git commit -m "chore(release): bump version to $VERSION"
86+
87+
# Create annotated tag
88+
echo "→ Creating tag v$VERSION"
89+
git tag -a "v$VERSION" -m "Release v$VERSION"
90+
91+
# Success message
92+
echo ""
93+
echo -e "${GREEN}🎉 Version bump complete!${NC}"
94+
echo ""
95+
echo "Summary:"
96+
echo " Version: $VERSION"
97+
echo " Commit: $(git rev-parse --short HEAD)"
98+
echo " Tag: v$VERSION"
99+
echo ""
100+
echo -e "${YELLOW}Next step:${NC}"
101+
echo " git push origin main && git push origin v$VERSION"
102+
echo ""
103+
echo "This will trigger the release workflow automatically."

0 commit comments

Comments
 (0)