Skip to content

Commit 64d5ca7

Browse files
PederzhPederzh
committed
chore: add beta release workflow and documentation
1 parent dc76a1c commit 64d5ca7

File tree

2 files changed

+344
-0
lines changed

2 files changed

+344
-0
lines changed

‎.github/workflows/release-beta.yml‎

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
name: Release Beta
2+
3+
on:
4+
push:
5+
branches:
6+
- beta
7+
workflow_dispatch: # Allow manual triggers
8+
9+
concurrency: ${{ github.workflow }}-${{ github.ref }}
10+
11+
jobs:
12+
release-beta:
13+
name: Release Beta
14+
runs-on: ubuntu-latest
15+
permissions:
16+
contents: write
17+
pull-requests: write
18+
id-token: write
19+
steps:
20+
- name: Checkout Repo
21+
uses: actions/checkout@v4
22+
with:
23+
fetch-depth: 0
24+
25+
- name: Setup pnpm
26+
uses: pnpm/action-setup@v3
27+
with:
28+
version: 10.6.1
29+
30+
- name: Setup Node.js
31+
uses: actions/setup-node@v4
32+
with:
33+
node-version: 22
34+
cache: 'pnpm'
35+
registry-url: 'https://registry.npmjs.org'
36+
37+
- name: Install Dependencies
38+
run: pnpm install --frozen-lockfile
39+
40+
- name: Build Packages
41+
run: pnpm build
42+
43+
- name: Check and Enter Prerelease Mode
44+
run: |
45+
# Check if already in prerelease mode
46+
if [ ! -f .changeset/pre.json ]; then
47+
echo "Entering prerelease mode with tag 'beta'"
48+
pnpm changeset pre enter beta
49+
git config user.name "github-actions[bot]"
50+
git config user.email "github-actions[bot]@users.noreply.github.com"
51+
git add .changeset/pre.json
52+
git commit -m "chore: enter beta prerelease mode" || echo "No changes to commit"
53+
git push || echo "No changes to push"
54+
else
55+
echo "Already in prerelease mode"
56+
cat .changeset/pre.json
57+
fi
58+
59+
- name: Create Release Pull Request or Publish to npm
60+
id: changesets
61+
uses: changesets/action@v1
62+
with:
63+
publish: pnpm release
64+
version: pnpm version
65+
commit: 'chore: version packages (beta)'
66+
title: 'chore: version packages (beta)'
67+
env:
68+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
69+
NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
70+
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
71+
72+
- name: Send Notification on Success
73+
if: steps.changesets.outputs.published == 'true'
74+
run: |
75+
echo "✅ Beta packages published successfully!"
76+
echo "Published packages: ${{ steps.changesets.outputs.publishedPackages }}"
77+
78+
- name: Comment on PR with Beta Version
79+
if: steps.changesets.outputs.published == 'true'
80+
uses: actions/github-script@v7
81+
with:
82+
script: |
83+
const packages = JSON.parse('${{ steps.changesets.outputs.publishedPackages }}');
84+
const packageList = packages.map(pkg => `- \`${pkg.name}@${pkg.version}\``).join('\n');
85+
86+
github.rest.repos.createCommitComment({
87+
owner: context.repo.owner,
88+
repo: context.repo.repo,
89+
commit_sha: context.sha,
90+
body: `## 🧪 Beta Release Published\n\n${packageList}\n\nInstall with:\n\`\`\`bash\nnpm install ${packages[0].name}@beta\n\`\`\``
91+
});
92+

‎BETA_RELEASES.md‎

Lines changed: 252 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,252 @@
1+
# Beta Release Workflow
2+
3+
This guide explains how to release beta versions using the `beta` branch and automated GitHub Actions.
4+
5+
## 🎯 Overview
6+
7+
- **`main` branch** → Stable releases (automated via `release.yml`)
8+
- **`beta` branch** → Beta/prerelease versions (automated via `release-beta.yml`)
9+
- Feature branches → Work in progress (no releases)
10+
11+
## 🚀 Quick Start: Releasing a Beta
12+
13+
### 1. Create and Push to Beta Branch
14+
15+
```bash
16+
# From your feature branch (e.g., feat/mcp-ui-apps)
17+
git checkout -b beta
18+
19+
# Push to trigger the beta release workflow
20+
git push origin beta
21+
```
22+
23+
The GitHub Action will automatically:
24+
- Enter prerelease mode (creates `.changeset/pre.json`)
25+
- Create a "Version Packages (beta)" PR
26+
- Publish beta versions when the PR is merged
27+
28+
### 2. Make Changes and Create Changesets
29+
30+
```bash
31+
# Make your changes
32+
# ... edit files ...
33+
34+
# Create a changeset
35+
pnpm changeset
36+
37+
# Commit and push
38+
git add .
39+
git commit -m "feat: add new feature"
40+
git push origin beta
41+
```
42+
43+
### 3. The Automated Flow
44+
45+
When you push to `beta`:
46+
47+
1. **If no changesets exist**: Nothing happens (waiting for changesets)
48+
2. **If changesets exist**:
49+
- A PR is created with version bumps (e.g., `0.2.1-beta.0`)
50+
- Review and merge the PR
51+
- On merge, packages are automatically published to npm with `@beta` tag
52+
53+
## 📝 Manual Beta Release (Alternative)
54+
55+
If you prefer manual control:
56+
57+
```bash
58+
# On beta branch
59+
git checkout beta
60+
61+
# Enter prerelease mode (first time only)
62+
pnpm changeset pre enter beta
63+
64+
# Create changesets
65+
pnpm changeset
66+
67+
# Version packages
68+
pnpm version
69+
70+
# Commit version changes
71+
git add .
72+
git commit -m "chore: version packages (beta)"
73+
git push
74+
75+
# Publish to npm
76+
pnpm release
77+
```
78+
79+
## 🔄 Continuous Beta Releases
80+
81+
While on the `beta` branch, you can continue making changes:
82+
83+
```bash
84+
# Make more changes
85+
# ... edit code ...
86+
87+
# Create another changeset
88+
pnpm changeset
89+
90+
# Push to trigger versioning
91+
git push origin beta
92+
```
93+
94+
Each release will increment the beta number: `0.2.1-beta.0` → `0.2.1-beta.1` → `0.2.1-beta.2`, etc.
95+
96+
## ✅ Promoting Beta to Stable
97+
98+
When beta testing is complete and you're ready for a stable release:
99+
100+
### Option 1: Merge Beta to Main (Recommended)
101+
102+
```bash
103+
# Switch to main and merge beta
104+
git checkout main
105+
git pull origin main
106+
git merge beta
107+
108+
# Exit prerelease mode
109+
pnpm changeset pre exit
110+
111+
# Commit the pre.json removal
112+
git add .changeset/pre.json
113+
git commit -m "chore: exit prerelease mode"
114+
115+
# Push to main (triggers stable release workflow)
116+
git push origin main
117+
```
118+
119+
The stable release workflow will:
120+
- Version packages as stable (e.g., `0.2.1`)
121+
- Publish to npm with `@latest` tag
122+
123+
### Option 2: Cherry-pick Changes
124+
125+
If you only want specific changes from beta:
126+
127+
```bash
128+
git checkout main
129+
git cherry-pick <commit-hash>
130+
# ... resolve any conflicts ...
131+
git push origin main
132+
```
133+
134+
## 📦 Installing Beta Versions
135+
136+
Users can install beta versions:
137+
138+
```bash
139+
# Install latest beta
140+
npm install mcp-use@beta
141+
npm install @mcp-use/cli@beta
142+
143+
# Install specific beta version
144+
npm install [email protected]
145+
```
146+
147+
## 🔍 Checking Beta Releases
148+
149+
View published versions and tags:
150+
151+
```bash
152+
# See all versions
153+
npm view mcp-use versions
154+
155+
# See dist-tags
156+
npm view mcp-use dist-tags
157+
# {
158+
# latest: '0.2.0',
159+
# beta: '0.2.1-beta.0'
160+
# }
161+
```
162+
163+
## 🛠️ Workflow Features
164+
165+
The `release-beta.yml` workflow includes:
166+
167+
- ✅ Automatic prerelease mode entry
168+
- ✅ Version PR creation
169+
- ✅ Automatic publishing on merge
170+
- ✅ Comment on commits with published versions
171+
- ✅ Manual trigger via GitHub UI (workflow_dispatch)
172+
173+
## 🔧 Manual Trigger
174+
175+
You can manually trigger a beta release from GitHub:
176+
177+
1. Go to **Actions** tab
178+
2. Select **Release Beta** workflow
179+
3. Click **Run workflow**
180+
4. Select `beta` branch
181+
5. Click **Run workflow** button
182+
183+
## 📋 Best Practices
184+
185+
1. **Keep beta branch up to date with main**
186+
```bash
187+
git checkout beta
188+
git merge main
189+
git push
190+
```
191+
192+
2. **Create meaningful changesets**
193+
- Describe what changed from a user's perspective
194+
- Mark breaking changes clearly
195+
196+
3. **Test beta versions thoroughly**
197+
- Install beta versions in test projects
198+
- Verify all packages work together
199+
- Check for breaking changes
200+
201+
4. **Clean up after stable release**
202+
```bash
203+
# After merging to main and releasing stable
204+
git checkout beta
205+
git merge main # Sync beta with main
206+
git push
207+
```
208+
209+
## 🐛 Troubleshooting
210+
211+
### "Already in prerelease mode" Error
212+
213+
The workflow handles this automatically, but if you see this message, it means `.changeset/pre.json` already exists. This is normal and expected.
214+
215+
### Beta Branch Out of Sync
216+
217+
```bash
218+
# Reset beta branch to match a starting point
219+
git checkout beta
220+
git reset --hard main # or feat/your-feature
221+
git push --force origin beta
222+
```
223+
224+
### Want to Start Fresh
225+
226+
```bash
227+
# Exit prerelease mode
228+
pnpm changeset pre exit
229+
230+
# Remove all pending changesets
231+
rm -rf .changeset/*.md
232+
233+
# Commit changes
234+
git add .
235+
git commit -m "chore: reset changesets"
236+
git push
237+
```
238+
239+
### Workflow Not Triggering
240+
241+
Check:
242+
1. Branch name is exactly `beta`
243+
2. You have changesets in `.changeset/*.md`
244+
3. GitHub Actions is enabled in your repository
245+
4. `NPM_TOKEN` secret is configured in GitHub Settings
246+
247+
## 📚 Resources
248+
249+
- [Changesets Prerelease Documentation](https://github.com/changesets/changesets/blob/main/docs/prereleases.md)
250+
- [Main Release Workflow](./VERSIONING.md)
251+
- [Changeset Workflow Guide](./CHANGESET_WORKFLOW.md)
252+

0 commit comments

Comments
 (0)