1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
|
# Release guide for doxx
This document outlines the complete release process for doxx, including automated pipelines and manual steps.
## 🎯 Release overview
The release pipeline includes:
- ✅ **Cross-platform binaries** (Linux, macOS Intel/ARM, Windows)
- ✅ **GitHub releases** with automated changelog
- ✅ **crates.io publishing** for `cargo install doxx`
- ✅ **Homebrew formula** (automated updates)
- ✅ **Checksums** for security verification
- ✅ **Modern GitHub Actions** with proper error handling
## 🚀 Quick release process
### 1. Prepare release
```bash
# Make sure you're on main branch and working directory is clean
git checkout main
git pull origin main
# Run the automated release script
./scripts/release.sh [major|minor|patch]
# Example for patch release (0.1.0 -> 0.1.1)
./scripts/release.sh patch
```
### 2. The script will:
- ✅ Bump version in `Cargo.toml`
- ✅ Run tests to ensure everything works
- ✅ Update `Cargo.lock`
- ✅ Commit version bump
- ✅ Create and push git tag (e.g., `v0.1.1`)
- ✅ Trigger GitHub Actions automatically
### 3. GitHub Actions will:
- ✅ Build cross-platform binaries (Linux musl, macOS Intel/ARM, Windows)
- ✅ Create draft GitHub release with CHANGELOG.md
- ✅ Generate SHA256 checksums
- ✅ Publish to crates.io (when draft is published)
- ✅ Update Homebrew formula automatically
### 4. Manual steps
1. **Review draft release**
- Go to [GitHub releases](https://github.com/bgreenwell/doxx/releases)
- Edit the draft release created by Actions
- Add release highlights and breaking changes if any
2. **Publish release**
- Click "Publish release" to make it live
- This triggers crates.io publishing
- Homebrew formula gets updated automatically
## 📦 Package manager status
### ✅ Active package managers
- **crates.io**: `cargo install doxx` ✅ Automated
- **GitHub releases**: Direct binary downloads ✅ Automated
- **Homebrew**: In progress 🚧 (Formula ready, tap needed)
### 🚧 Future package managers
- **Scoop** (Windows): Repository structure ready
- **Chocolatey** (Windows): Future consideration
- **Snap** (Linux): Future consideration
- **AUR** (Arch Linux): Community contribution welcome
## 🔍 Testing release pipeline
### Test without publishing
```bash
# Test packaging for crates.io (dry run)
cargo publish --dry-run
# Test binary builds locally
cargo build --release --target x86_64-unknown-linux-musl
cargo build --release --target x86_64-apple-darwin
# Test CLI works correctly
./target/release/doxx --version
./target/release/doxx tests/fixtures/minimal.docx --export text
```
### Verify release assets
After GitHub release is published:
```bash
# Download and verify checksums
wget https://github.com/bgreenwell/doxx/releases/latest/download/doxx-checksums.txt
wget https://github.com/bgreenwell/doxx/releases/latest/download/doxx-linux-x86_64.tar.gz
# Verify checksum matches
sha256sum doxx-linux-x86_64.tar.gz
grep linux-x86_64 doxx-checksums.txt
```
## 📋 Pre-release checklist
- [ ] All CI/CD tests passing on main branch
- [ ] `CHANGELOG.md` updated with release notes
- [ ] Version number follows semantic versioning
- [ ] All new features documented in README
- [ ] Breaking changes clearly documented
- [ ] Security issues addressed
- [ ] Dependencies updated and audited
## 🛠 Troubleshooting
### Release script issues
```bash
# If release script fails, check:
git status # Working directory clean?
cargo test --all-features # All tests pass?
cargo clippy -- -D warnings # No linting issues?
```
### GitHub Actions issues
- Check Actions tab for build failures
- Common issues: Missing secrets (`CARGO_REGISTRY_TOKEN`)
- Platform-specific build failures (usually dependency issues)
### crates.io publishing issues
- Ensure `CARGO_REGISTRY_TOKEN` secret is set
- Verify all required metadata in `Cargo.toml`
- Check for naming conflicts
## 🔐 Required secrets
Repository secrets needed for full automation:
- `CARGO_REGISTRY_TOKEN`: For publishing to crates.io
- Get from https://crates.io/me
- Scope: "Publish new crates and update existing crates"
## 📈 Success metrics
After release, verify:
- [ ] GitHub release created with all binary assets
- [ ] crates.io shows new version (may take a few minutes)
- [ ] `cargo install doxx` works with new version
- [ ] Download links in README work correctly
- [ ] Homebrew formula updated (if tap is public)
## 🎉 Post-release
1. **Announce release**
- Update README badges if needed
- Consider social media announcement
- Update any documentation sites
2. **Monitor**
- Watch for user issues or bug reports
- Monitor download statistics
- Track performance metrics
---
**Need help?** Check the GitHub Actions logs or open an issue for release pipeline problems.
|
