Skip to content

Commit a200118

Browse files
nielspeternielspeter
authored
docs: Add changelog and release documentation system (#6)
* docs: Add comprehensive changelog and release documentation system This commit adds a complete release management system including: 1. CHANGELOG.md - Full changelog for v1.0.0 and v1.1.0 releases - Follows Keep a Changelog format - Categorizes changes: Added, Changed, Fixed, etc. - Includes upgrade guide 2. Release Documentation - .github/RELEASE_TEMPLATE.md: Step-by-step release checklist - .github/RELEASE_WORKFLOW.md: Complete workflow guide - Conventional commits guidelines - Semantic versioning strategy 3. Automated Release Workflow - Updated .github/workflows/release.yml - Automatically extracts release notes from CHANGELOG.md - Falls back to auto-generated notes if section missing - Includes installation instructions in all releases 4. Professional Badges - Added shields.io badges to README.md - Version, Go version, build status, license, issues 5. Test Coverage - Comprehensive unit tests for reasoning model detection - 36 new test cases covering: - Hardcoded pattern fallback - OpenRouter API cache behavior - Provider-specific detection - Edge cases and error handling - Updated existing converter tests All tests pass: - internal/config: 36 new tests ✅ - internal/converter: All tests passing ✅ - Build successful ✅ 🤖 Generated with Claude Code * fix: Handle resp.Body.Close() error in FetchReasoningModels Addresses golangci-lint errcheck warning by explicitly ignoring the Body.Close() error using blank identifier in defer function. This is the standard pattern for handling Close() errors in deferred cleanup where we can't meaningfully handle the error.
1 parent 4d77643 commit a200118

File tree

10 files changed

+1103
-81
lines changed

10 files changed

+1103
-81
lines changed

‎.github/RELEASE_TEMPLATE.md‎

Lines changed: 113 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
# Release Template
2+
3+
Use this template when preparing a new release.
4+
5+
## Pre-Release Checklist
6+
7+
- [ ] Update version number in relevant files
8+
- [ ] Update CHANGELOG.md with new version
9+
- [ ] Run full test suite: `go test ./...`
10+
- [ ] Run linter: `golangci-lint run`
11+
- [ ] Build for all platforms: `make build-all`
12+
- [ ] Test the `ccp` wrapper locally
13+
- [ ] Update documentation if needed
14+
15+
## CHANGELOG.md Template
16+
17+
```markdown
18+
## [X.Y.Z] - YYYY-MM-DD
19+
20+
### Added
21+
- New feature description
22+
23+
### Changed
24+
- Changed feature description
25+
26+
### Fixed
27+
- Bug fix description
28+
29+
### Removed
30+
- Removed feature description
31+
32+
### Security
33+
- Security fix description
34+
```
35+
36+
## Creating the Release
37+
38+
### 1. Update CHANGELOG.md
39+
Move items from `[Unreleased]` section to new version section:
40+
41+
```bash
42+
# Example for v1.2.0
43+
vim CHANGELOG.md
44+
# Move unreleased changes to new [1.2.0] section
45+
# Add release date
46+
```
47+
48+
### 2. Commit the changelog
49+
```bash
50+
git add CHANGELOG.md
51+
git commit -m "docs: Update CHANGELOG for v1.2.0"
52+
git push
53+
```
54+
55+
### 3. Create Git Tag
56+
```bash
57+
git tag -a v1.2.0 -m "Release v1.2.0: Brief description"
58+
git push origin v1.2.0
59+
```
60+
61+
### 4. Create GitHub Release
62+
```bash
63+
gh release create v1.2.0 \
64+
--title "v1.2.0 - Release Title" \
65+
--notes-file <(sed -n '/## \[1.2.0\]/,/## \[/p' CHANGELOG.md | head -n -1)
66+
```
67+
68+
Or manually via GitHub UI:
69+
1. Go to https://github.com/nielspeter/claude-code-proxy/releases/new
70+
2. Select tag: `v1.2.0`
71+
3. Copy release notes from CHANGELOG.md
72+
4. Publish release
73+
74+
## Semantic Versioning Guidelines
75+
76+
- **MAJOR** (X.0.0): Breaking changes, incompatible API changes
77+
- **MINOR** (1.X.0): New features, backward-compatible
78+
- **PATCH** (1.1.X): Bug fixes, backward-compatible
79+
80+
### Examples
81+
82+
- `v1.2.0`: Added new model provider support ✅ MINOR
83+
- `v1.1.1`: Fixed streaming bug ✅ PATCH
84+
- `v2.0.0`: Changed config file format (breaking) ✅ MAJOR
85+
86+
## Conventional Commits
87+
88+
Use these prefixes for commits (helps with changelog generation):
89+
90+
- `feat:` - New feature (MINOR version bump)
91+
- `fix:` - Bug fix (PATCH version bump)
92+
- `docs:` - Documentation only
93+
- `refactor:` - Code refactoring
94+
- `test:` - Adding tests
95+
- `chore:` - Maintenance tasks
96+
- `perf:` - Performance improvements
97+
- `ci:` - CI/CD changes
98+
99+
### Examples
100+
```bash
101+
feat: Add support for Azure OpenAI provider
102+
fix: Resolve streaming token count issue
103+
docs: Update installation instructions
104+
test: Add unit tests for model detection
105+
```
106+
107+
## Post-Release Tasks
108+
109+
- [ ] Verify release appears on GitHub
110+
- [ ] Test installation from release binaries
111+
- [ ] Announce release (if applicable)
112+
- [ ] Update any dependent projects
113+
- [ ] Start new `[Unreleased]` section in CHANGELOG.md

‎.github/RELEASE_WORKFLOW.md‎

Lines changed: 201 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,201 @@
1+
# Release Workflow Guide
2+
3+
This guide explains how to create releases for claude-code-proxy.
4+
5+
## Files Created
6+
7+
1. **`CHANGELOG.md`** - Main changelog following [Keep a Changelog](https://keepachangelog.com/) format
8+
2. **`.github/RELEASE_TEMPLATE.md`** - Template and checklist for creating releases
9+
3. **`.github/workflows/release.yml`** - Automated GitHub Actions workflow (updated)
10+
11+
## Quick Release Process
12+
13+
### 1. Update CHANGELOG.md
14+
15+
Before creating a release, move unreleased changes to a new version section:
16+
17+
```bash
18+
# Edit CHANGELOG.md
19+
vim CHANGELOG.md
20+
```
21+
22+
Change:
23+
```markdown
24+
## [Unreleased]
25+
### Added
26+
- New feature X
27+
- New feature Y
28+
```
29+
30+
To:
31+
```markdown
32+
## [Unreleased]
33+
34+
## [1.2.0] - 2025-11-02
35+
### Added
36+
- New feature X
37+
- New feature Y
38+
```
39+
40+
### 2. Commit and Push
41+
42+
```bash
43+
git add CHANGELOG.md
44+
git commit -m "docs: Update CHANGELOG for v1.2.0"
45+
git push
46+
```
47+
48+
### 3. Create and Push Tag
49+
50+
```bash
51+
git tag -a v1.2.0 -m "Release v1.2.0: Brief description"
52+
git push origin v1.2.0
53+
```
54+
55+
### 4. Automated Release
56+
57+
The GitHub Action will automatically:
58+
- ✅ Run all tests
59+
- ✅ Build binaries for all platforms (Linux, macOS, Windows, ARM, x86)
60+
- ✅ Create checksums
61+
- ✅ Extract release notes from CHANGELOG.md
62+
- ✅ Create GitHub release with installation instructions
63+
- ✅ Upload all binaries to the release
64+
65+
## What the Workflow Does
66+
67+
### If CHANGELOG.md has section for this version:
68+
1. Extracts your curated changelog content
69+
2. Appends installation instructions
70+
3. Uses your changelog as release notes
71+
72+
### If no CHANGELOG.md section found:
73+
1. Falls back to auto-generated release notes from PRs
74+
2. Adds installation instructions
75+
76+
## Example CHANGELOG.md Structure
77+
78+
```markdown
79+
# Changelog
80+
81+
## [Unreleased]
82+
### Added
83+
- Feature still in development
84+
85+
## [1.2.0] - 2025-11-02
86+
### Added
87+
- Dynamic model detection from provider API
88+
- Support for new reasoning models
89+
90+
### Fixed
91+
- Token counting issue in streaming mode
92+
93+
### Changed
94+
- Improved error handling
95+
96+
## [1.1.0] - 2025-10-31
97+
### Added
98+
- Reasoning model support
99+
100+
## [1.0.0] - 2025-10-26
101+
### Added
102+
- Initial release
103+
```
104+
105+
## Conventional Commits (Recommended)
106+
107+
Using conventional commits makes it easier to categorize changes:
108+
109+
```bash
110+
# Features (go in "Added" section)
111+
git commit -m "feat: Add support for Azure OpenAI"
112+
113+
# Bug fixes (go in "Fixed" section)
114+
git commit -m "fix: Resolve streaming timeout issue"
115+
116+
# Documentation (go in "Changed" section if user-facing)
117+
git commit -m "docs: Update installation guide"
118+
119+
# Tests (usually not in changelog)
120+
git commit -m "test: Add unit tests for model detection"
121+
122+
# Refactoring (go in "Changed" if user-facing)
123+
git commit -m "refactor: Simplify config loading"
124+
```
125+
126+
## Versioning Strategy
127+
128+
Follow [Semantic Versioning](https://semver.org/):
129+
130+
- **MAJOR** (2.0.0): Breaking changes
131+
- Example: Changed config file format
132+
- Example: Removed deprecated API
133+
134+
- **MINOR** (1.X.0): New features, backward-compatible
135+
- Example: Added support for new provider
136+
- Example: Added new CLI flag
137+
138+
- **PATCH** (1.1.X): Bug fixes, backward-compatible
139+
- Example: Fixed token counting bug
140+
- Example: Fixed crash on startup
141+
142+
## Troubleshooting
143+
144+
### Release workflow failed?
145+
146+
Check:
147+
1. Did you run `make build-all` locally first to verify builds work?
148+
2. Did you update CHANGELOG.md with the version number?
149+
3. Did the tag format match `v*.*.*` (e.g., `v1.2.0` not `1.2.0`)?
150+
151+
### Release notes look wrong?
152+
153+
1. Check that CHANGELOG.md has a section `## [1.2.0]` matching your tag `v1.2.0`
154+
2. The section should be between the version heading and the next version heading
155+
3. Make sure there's proper markdown formatting
156+
157+
### Want to test locally?
158+
159+
```bash
160+
# Test changelog extraction
161+
VERSION="1.2.0"
162+
sed -n "/## \[${VERSION}\]/,/## \[/p" CHANGELOG.md | sed '$d' | tail -n +2
163+
164+
# Test builds
165+
make build-all
166+
cd dist && sha256sum * > checksums.txt
167+
```
168+
169+
## Manual Release (if needed)
170+
171+
If you need to create a release manually:
172+
173+
```bash
174+
# Create release via GitHub CLI
175+
gh release create v1.2.0 \
176+
--title "v1.2.0 - Release Title" \
177+
--notes "$(sed -n '/## \[1.2.0\]/,/## \[/p' CHANGELOG.md | sed '$d' | tail -n +2)" \
178+
dist/*
179+
```
180+
181+
Or use the GitHub web interface:
182+
1. Go to: https://github.com/nielspeter/claude-code-proxy/releases/new
183+
2. Choose tag: `v1.2.0`
184+
3. Copy content from CHANGELOG.md for that version
185+
4. Upload binaries from `dist/` folder
186+
5. Publish
187+
188+
## Tips
189+
190+
1. **Keep Unreleased section active**: Always have an `[Unreleased]` section at the top for ongoing work
191+
2. **Update CHANGELOG as you go**: Don't wait until release time to document changes
192+
3. **Link to issues/PRs**: Add links like `(#123)` for context
193+
4. **Be concise**: Focus on user-facing changes, not internal refactoring (unless significant)
194+
5. **Test first**: Always run tests and build locally before tagging
195+
196+
## Questions?
197+
198+
See:
199+
- `.github/RELEASE_TEMPLATE.md` for detailed checklist
200+
- `CHANGELOG.md` for examples of good changelog entries
201+
- [Keep a Changelog](https://keepachangelog.com/) for format guidelines

0 commit comments

Comments
 (0)