Skip to content

Commit b2827f8

Browse files
gnodetgnodet
authored
feat: add dynamic changelog generation and release documentation (#35)
- Add scripts/generate-changelog.sh for automatic changelog generation from git commits - Update .github/workflows/release.yml to use dynamic changelog instead of static notes - Add RELEASING.md with comprehensive release process documentation - Add changelog command to .mvx/config.json5 for manual changelog generation - Categorizes commits by type: features, fixes, improvements, docs, breaking changes - Supports conventional commit format and keyword-based detection - Generates professional release notes with proper formatting and GitHub links Resolves the issue of identical release notes by providing actual change information.
1 parent a2ac230 commit b2827f8

File tree

4 files changed

+474
-31
lines changed

4 files changed

+474
-31
lines changed

‎.github/workflows/release.yml‎

Lines changed: 41 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -132,58 +132,68 @@ jobs:
132132
133133
- name: Generate release notes
134134
run: |
135-
cat > release_notes.md << 'EOF'
135+
# Make sure the changelog script is executable
136+
chmod +x ./scripts/generate-changelog.sh
137+
138+
# Get the previous tag for changelog generation
139+
PREVIOUS_TAG=$(git describe --tags --abbrev=0 ${{ steps.version.outputs.version }}^ 2>/dev/null || echo "")
140+
141+
# Generate the changelog section
142+
if [ -n "$PREVIOUS_TAG" ]; then
143+
echo "Generating changelog from $PREVIOUS_TAG to ${{ steps.version.outputs.version }}"
144+
CHANGELOG=$(./scripts/generate-changelog.sh "$PREVIOUS_TAG" "${{ steps.version.outputs.version }}")
145+
else
146+
echo "No previous tag found, using generic changelog"
147+
CHANGELOG="## 🚀 What's New
148+
149+
This is the first release of mvx!"
150+
fi
151+
152+
# Create the complete release notes
153+
cat > release_notes.md << EOF
136154
## mvx ${{ steps.version.outputs.version_no_v }}
137-
155+
156+
$CHANGELOG
157+
138158
### 🚀 Installation
139-
159+
140160
**Using the wrapper (recommended):**
141-
```bash
161+
\`\`\`bash
142162
curl -fsSL https://raw.githubusercontent.com/gnodet/mvx/main/install-wrapper.sh | bash
143163
./mvx version
144-
```
145-
164+
\`\`\`
165+
146166
**Direct download:**
147-
```bash
167+
\`\`\`bash
148168
# Linux x64
149169
curl -fsSL https://github.com/gnodet/mvx/releases/download/${{ steps.version.outputs.version }}/mvx-linux-amd64 -o mvx
150170
chmod +x mvx
151-
171+
152172
# macOS x64
153173
curl -fsSL https://github.com/gnodet/mvx/releases/download/${{ steps.version.outputs.version }}/mvx-darwin-amd64 -o mvx
154174
chmod +x mvx
155-
175+
156176
# Windows x64
157177
curl -fsSL https://github.com/gnodet/mvx/releases/download/${{ steps.version.outputs.version }}/mvx-windows-amd64.exe -o mvx.exe
158-
```
159-
178+
\`\`\`
179+
160180
### 📦 Assets
161-
181+
162182
| Platform | Architecture | Binary | Checksum |
163183
|----------|--------------|--------|----------|
164-
| Linux | x64 | `mvx-linux-amd64` | `mvx-linux-amd64.sha256` |
165-
| Linux | ARM64 | `mvx-linux-arm64` | `mvx-linux-arm64.sha256` |
166-
| macOS | x64 | `mvx-darwin-amd64` | `mvx-darwin-amd64.sha256` |
167-
| macOS | ARM64 | `mvx-darwin-arm64` | `mvx-darwin-arm64.sha256` |
168-
| Windows | x64 | `mvx-windows-amd64.exe` | `mvx-windows-amd64.exe.sha256` |
169-
184+
| Linux | x64 | \`mvx-linux-amd64\` | \`mvx-linux-amd64.sha256\` |
185+
| Linux | ARM64 | \`mvx-linux-arm64\` | \`mvx-linux-arm64.sha256\` |
186+
| macOS | x64 | \`mvx-darwin-amd64\` | \`mvx-darwin-amd64.sha256\` |
187+
| macOS | ARM64 | \`mvx-darwin-arm64\` | \`mvx-darwin-arm64.sha256\` |
188+
| Windows | x64 | \`mvx-windows-amd64.exe\` | \`mvx-windows-amd64.exe.sha256\` |
189+
170190
### 🔐 Verification
171-
191+
172192
Verify checksums:
173-
```bash
193+
\`\`\`bash
174194
curl -fsSL https://github.com/gnodet/mvx/releases/download/${{ steps.version.outputs.version }}/checksums.txt
175195
sha256sum -c checksums.txt
176-
```
177-
178-
### 📋 What's New
179-
180-
- Universal build environment bootstrap tool
181-
- Zero-dependency installation via wrapper scripts
182-
- Cross-platform support (Linux, macOS, Windows)
183-
- Multi-architecture support (amd64, arm64)
184-
- Tool management for Java, Maven, Node.js, Python, and more
185-
- Project-specific environment configuration
186-
196+
\`\`\`
187197
EOF
188198
189199
- name: Create release

‎.mvx/config.json5‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -98,6 +98,11 @@
9898
description: "Clean build artifacts",
9999
script: "rm -f mvx-dev && rm -rf dist/ && rm -f ~/.mvx/dev/mvx && echo '🧹 Cleaned local and global dev binaries'",
100100
override: true
101+
},
102+
103+
changelog: {
104+
description: "Generate changelog between two git tags/commits",
105+
script: "./scripts/generate-changelog.sh"
101106
}
102107
}
103108
}

‎RELEASING.md‎

Lines changed: 217 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,217 @@
1+
# Releasing mvx
2+
3+
This document describes the process for creating a new release of mvx.
4+
5+
## Prerequisites
6+
7+
Before creating a release, ensure you have:
8+
9+
1. **Git repository access**: Push access to the main repository
10+
2. **Clean working directory**: No uncommitted changes
11+
3. **All tests passing**: Run `./mvx test` to verify
12+
4. **Updated documentation**: Ensure all changes are documented
13+
5. **Version decision**: Decide on the version number following [Semantic Versioning](https://semver.org/)
14+
15+
## Version Numbering
16+
17+
mvx follows [Semantic Versioning](https://semver.org/):
18+
19+
- **MAJOR** version (e.g., `v1.0.0` → `v2.0.0`): Breaking changes
20+
- **MINOR** version (e.g., `v1.0.0` → `v1.1.0`): New features, backward compatible
21+
- **PATCH** version (e.g., `v1.0.0` → `v1.0.1`): Bug fixes, backward compatible
22+
23+
## Release Process
24+
25+
### 1. Prepare the Release
26+
27+
```bash
28+
# Ensure you're on the main branch
29+
git checkout main
30+
git pull origin main
31+
32+
# Verify the working directory is clean
33+
git status
34+
35+
# Run tests to ensure everything works
36+
./mvx test
37+
38+
# Optional: Preview the changelog for the upcoming release
39+
./mvx changelog # Shows changes since last tag
40+
```
41+
42+
### 2. Create the Release
43+
44+
Use the release script to automate the process:
45+
46+
```bash
47+
# Create a new release (replace with your version)
48+
./scripts/release.sh v1.2.3
49+
```
50+
51+
The release script will:
52+
1. ✅ Validate the version format
53+
2. ✅ Check that the tag doesn't already exist
54+
3. ✅ Run tests to ensure everything works
55+
4. ✅ Build binaries for all platforms
56+
5. ✅ Generate checksums
57+
6. ✅ Create and push the git tag
58+
7. ✅ Trigger GitHub Actions to create the release
59+
60+
### 3. Monitor the Release
61+
62+
After running the release script:
63+
64+
1. **Check GitHub Actions**: Visit [Actions tab](https://github.com/gnodet/mvx/actions) to monitor the release workflow
65+
2. **Verify the release**: Once complete, check the [Releases page](https://github.com/gnodet/mvx/releases)
66+
3. **Test the release**: Download and test the released binaries
67+
68+
## What Happens Automatically
69+
70+
When you push a tag, GitHub Actions automatically:
71+
72+
1. **Builds binaries** for all supported platforms (Linux, macOS, Windows) and architectures (amd64, arm64)
73+
2. **Generates checksums** for all binaries
74+
3. **Creates release notes** with:
75+
- Automatic changelog generated from git commits since the last release
76+
- Installation instructions
77+
- Asset table with download links
78+
- Checksum verification instructions
79+
4. **Publishes the release** on GitHub
80+
81+
## Changelog Generation
82+
83+
The release process automatically generates a changelog by analyzing git commits between releases. Commits are categorized as:
84+
85+
- **✨ New Features**: `feat:` prefix or keywords like "add", "implement", "introduce"
86+
- **🐛 Bug Fixes**: `fix:` prefix or keywords like "fix", "bug", "resolve"
87+
- **🔧 Improvements**: `refactor:`, `perf:`, `style:`, `test:` prefixes or keywords like "enhance", "improve", "optimize", "update"
88+
- **📚 Documentation**: `docs:` prefix or keywords like "docs", "documentation", "readme", "website"
89+
- **⚠️ Breaking Changes**: `!` in commit message or "breaking" keyword
90+
- **🔄 Other Changes**: Everything else
91+
92+
### Writing Good Commit Messages
93+
94+
To ensure good changelog generation, write descriptive commit messages:
95+
96+
```bash
97+
# Good examples
98+
git commit -m "feat: add Node.js tool support"
99+
git commit -m "fix: resolve TLS timeout issues in downloads"
100+
git commit -m "docs: update installation instructions"
101+
git commit -m "refactor: improve Maven version resolution"
102+
103+
# Less ideal (but still works)
104+
git commit -m "Add support for Node.js"
105+
git commit -m "Fix timeout bug"
106+
```
107+
108+
## Manual Changelog Generation
109+
110+
You can generate a changelog manually for any range:
111+
112+
```bash
113+
# Between two tags
114+
./mvx changelog v1.0.0 v1.1.0
115+
116+
# From a tag to current HEAD
117+
./mvx changelog v1.0.0 HEAD
118+
119+
# From latest tag to HEAD (default)
120+
./mvx changelog
121+
```
122+
123+
## Testing a Release
124+
125+
After a release is published, test it:
126+
127+
```bash
128+
# Test the wrapper installation
129+
curl -fsSL https://raw.githubusercontent.com/gnodet/mvx/main/install-wrapper.sh | bash
130+
./mvx version
131+
132+
# Test direct binary download
133+
curl -fsSL https://github.com/gnodet/mvx/releases/download/v1.2.3/mvx-linux-amd64 -o mvx-test
134+
chmod +x mvx-test
135+
./mvx-test version
136+
137+
# Verify checksums
138+
curl -fsSL https://github.com/gnodet/mvx/releases/download/v1.2.3/checksums.txt
139+
sha256sum -c checksums.txt
140+
```
141+
142+
## Troubleshooting
143+
144+
### Release Script Fails
145+
146+
If `./scripts/release.sh` fails:
147+
148+
1. **Check git status**: Ensure working directory is clean
149+
2. **Verify tests**: Run `./mvx test` manually
150+
3. **Check version format**: Must be `vX.Y.Z` format
151+
4. **Verify tag doesn't exist**: `git tag -l | grep v1.2.3`
152+
153+
### GitHub Actions Fails
154+
155+
If the GitHub Actions workflow fails:
156+
157+
1. **Check the Actions tab**: Look for error messages
158+
2. **Common issues**:
159+
- Network timeouts during downloads
160+
- Build failures due to code issues
161+
- Permission issues with GitHub token
162+
163+
### Release Notes Are Wrong
164+
165+
If the generated changelog is incorrect:
166+
167+
1. **Check commit messages**: Ensure they follow conventions
168+
2. **Manual edit**: Edit the release on GitHub after it's created
169+
3. **Improve commit messages**: For future releases
170+
171+
## Emergency Procedures
172+
173+
### Delete a Bad Release
174+
175+
If you need to delete a release:
176+
177+
```bash
178+
# Delete the tag locally and remotely
179+
git tag -d v1.2.3
180+
git push origin :refs/tags/v1.2.3
181+
182+
# Delete the GitHub release manually via the web interface
183+
```
184+
185+
### Hotfix Release
186+
187+
For urgent fixes:
188+
189+
1. Create a hotfix branch from the release tag
190+
2. Apply the minimal fix
191+
3. Create a patch release (e.g., `v1.2.3` → `v1.2.4`)
192+
4. Follow the normal release process
193+
194+
## Post-Release Tasks
195+
196+
After a successful release:
197+
198+
1. **Update documentation**: If needed for the new version
199+
2. **Announce the release**: In relevant channels/communities
200+
3. **Update dependent projects**: If you maintain projects that use mvx
201+
4. **Monitor for issues**: Watch for bug reports related to the new release
202+
203+
## Release Checklist
204+
205+
- [ ] Working directory is clean (`git status`)
206+
- [ ] All tests pass (`./mvx test`)
207+
- [ ] Version number decided (following semver)
208+
- [ ] Release script executed (`./scripts/release.sh vX.Y.Z`)
209+
- [ ] GitHub Actions completed successfully
210+
- [ ] Release published on GitHub
211+
- [ ] Release tested with wrapper and direct download
212+
- [ ] Checksums verified
213+
- [ ] Documentation updated if needed
214+
215+
---
216+
217+
For questions or issues with the release process, please [open an issue](https://github.com/gnodet/mvx/issues) or [start a discussion](https://github.com/gnodet/mvx/discussions).

0 commit comments

Comments
 (0)