Skip to content

Commit 204258b

Browse files
pankgeorgclaude
pankgeorg
and
claude
committed
chore: add release workflow docs, license placeholder, test notebooks
LICENSE currently reads 'Not licensed yet (bear with us!)' which contradicts the MIT declared in both package.jsons — committed as-is, reconcile before publishing. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
1 parent 6a1ce1d commit 204258b

6 files changed

Lines changed: 732 additions & 0 deletions

File tree

‎.releaserc.with-commit.json‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
{
2+
"branches": ["main"],
3+
"plugins": [
4+
"@semantic-release/commit-analyzer",
5+
"@semantic-release/release-notes-generator",
6+
"@semantic-release/changelog",
7+
[
8+
"@semantic-release/npm",
9+
{
10+
"npmPublish": false
11+
}
12+
],
13+
[
14+
"semantic-release-vsce",
15+
{
16+
"packageVsix": true
17+
}
18+
],
19+
[
20+
"@semantic-release/github",
21+
{
22+
"assets": [
23+
{
24+
"path": "*.vsix",
25+
"label": "VS Code Extension (VSIX)"
26+
},
27+
{
28+
"path": "CHANGELOG.md",
29+
"label": "Changelog"
30+
}
31+
]
32+
}
33+
],
34+
[
35+
"@semantic-release/git",
36+
{
37+
"assets": ["package.json", "CHANGELOG.md"],
38+
"message": "chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}"
39+
}
40+
]
41+
]
42+
}

‎LICENSE‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
Not licensed yet (bear with us!)

‎a.pluto.jl‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
### A Pluto.jl notebook ###
2+
# v0.20.19
3+
4+
using Markdown
5+
using InteractiveUtils
6+
7+
# ╔═╡ d3289ef4-a7b8-11f0-2cb7-e1f1fe736ff6
8+
# ╠═╡ disabled = false
9+
# ╠═╡ show_logs = true
10+
# ╠═╡ skip_as_script = false
11+
using PlutoUI
12+
13+
# ╔═╡ be82cf10-a5ba-43e9-9ff5-c75a3dbeca7a
14+
# ╠═╡ show_logs = false
15+
# ╠═╡ disabled = false
16+
# ╠═╡ show_logs = false
17+
# ╠═╡ skip_as_script = false
18+
@bind x Slider(0:0.1:10)
19+
20+
# ╔═╡ 73225838-d89e-4008-929c-27fa92dd99ec
21+
# ╠═╡ show_logs = false
22+
# ╠═╡ disabled = false
23+
# ╠═╡ show_logs = false
24+
# ╠═╡ skip_as_script = false
25+
1+2
26+
27+
# ╔═╡ e0b2289c-8492-4674-90fd-f3178de4de19
28+
# ╠═╡ show_logs = false
29+
# ╠═╡ disabled = false
30+
# ╠═╡ show_logs = false
31+
# ╠═╡ skip_as_script = false
32+
x
33+
34+
# ╔═╡ 9470219e-00fa-4312-9cec-f31ac04bb26f
35+
# ╠═╡ show_logs = false
36+
# ╠═╡ disabled = false
37+
# ╠═╡ show_logs = false
38+
# ╠═╡ skip_as_script = false
39+
1+6
40+
41+
# ╔═╡ b8952e6e-346b-4cb3-babb-2106f8e39b2d
42+
# ╠═╡ show_logs = false
43+
# ╠═╡ disabled = false
44+
# ╠═╡ show_logs = false
45+
# ╠═╡ skip_as_script = false
46+
47+
48+
# ╔═╡ Cell order:
49+
# ╠═d3289ef4-a7b8-11f0-2cb7-e1f1fe736ff6
50+
# ╠═be82cf10-a5ba-43e9-9ff5-c75a3dbeca7a
51+
# ╠═73225838-d89e-4008-929c-27fa92dd99ec
52+
# ╠═e0b2289c-8492-4674-90fd-f3178de4de19
53+
# ╠═9470219e-00fa-4312-9cec-f31ac04bb26f
54+
# ╠═b8952e6e-346b-4cb3-babb-2106f8e39b2d

‎docs/RELEASE_WORKFLOW.md‎

Lines changed: 178 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,178 @@
1+
# Release Workflow
2+
3+
This project uses semantic-release in **no-commit mode** to handle releases.
4+
5+
## How It Works
6+
7+
When commits are pushed to `main`, the release workflow:
8+
9+
1. ✅ Analyzes commit messages to determine version bump (feat = minor, fix = patch, etc.)
10+
2. ✅ Generates release notes from commits
11+
3. ✅ Packages the extension as a VSIX file
12+
4. ✅ Creates a GitHub release with the VSIX attached
13+
5. ✅ Tags the release
14+
6. ❌ **Does NOT** push version changes back to the repository
15+
16+
## Why No-Commit Mode?
17+
18+
We use no-commit mode because:
19+
20+
- GitHub Rulesets protect the main branch
21+
- No need to configure PAT bypass for pushing commits
22+
- Simpler workflow with fewer permissions required
23+
- Version bumps are manual and intentional
24+
25+
## Managing Versions
26+
27+
Since semantic-release doesn't update `package.json` automatically, you need to update versions manually.
28+
29+
### Before Making a Release
30+
31+
1. Update version in `package.json`:
32+
33+
```json
34+
{
35+
"version": "0.2.0-alpha"
36+
}
37+
```
38+
39+
2. Update `CHANGELOG.md`:
40+
41+
```markdown
42+
## [Unreleased]
43+
44+
## [0.2.0-alpha] - 2025-10-13
45+
46+
### Added
47+
48+
- New feature here
49+
```
50+
51+
3. Commit the changes:
52+
53+
```bash
54+
git add package.json CHANGELOG.md
55+
git commit -m "chore: bump version to 0.2.0-alpha"
56+
git push origin main
57+
```
58+
59+
4. The release workflow will automatically:
60+
- Build the VSIX with the new version
61+
- Create a GitHub release
62+
- Attach the VSIX artifact
63+
- Use your CHANGELOG content in release notes
64+
65+
### Versioning Strategy
66+
67+
We use semantic versioning with alpha/beta tags during early development:
68+
69+
- `0.1.0-alpha` - Initial alpha release
70+
- `0.2.0-alpha` - Second alpha with new features
71+
- `0.2.1-alpha` - Alpha patch release
72+
- `0.3.0-beta` - First beta release
73+
- `1.0.0` - First stable release
74+
75+
### Conventional Commits
76+
77+
Use conventional commits for automatic release note generation:
78+
79+
- `feat: add new feature` → Adds to "Features" section
80+
- `fix: resolve bug` → Adds to "Bug Fixes" section
81+
- `docs: update readme` → Adds to "Documentation" section
82+
- `chore: update deps` → Adds to "Maintenance" section
83+
- `BREAKING CHANGE:` → Highlights breaking changes
84+
85+
## Manual Release Trigger
86+
87+
You can trigger a release manually from GitHub Actions:
88+
89+
1. Go to Actions → Release workflow
90+
2. Click "Run workflow"
91+
3. Select branch: `main`
92+
4. Choose dry-run option if testing
93+
5. Click "Run workflow"
94+
95+
## Dry Run Testing
96+
97+
Test the release process without creating an actual release:
98+
99+
```bash
100+
npx semantic-release --dry-run
101+
```
102+
103+
This will:
104+
105+
- Analyze commits
106+
- Determine what version would be released
107+
- Show what files would be included
108+
- Not create any release or tag
109+
110+
## Switching to With-Commit Mode
111+
112+
If you later want semantic-release to automatically update versions:
113+
114+
```bash
115+
# Switch configs
116+
mv .releaserc.json .releaserc.no-commit.json
117+
mv .releaserc.with-commit.json .releaserc.json
118+
119+
# Update workflow
120+
# Edit .github/workflows/release.yml:
121+
# - Add GH_PAT token configuration
122+
# - Add git committer environment variables
123+
124+
# Commit
125+
git add .releaserc.json .releaserc.with-commit.json .github/workflows/release.yml
126+
git commit -m "chore: switch to semantic-release with commits"
127+
git push
128+
```
129+
130+
See `docs/RULESETS_QUICK_FIX.md` for setting up PAT bypass with GitHub Rulesets.
131+
132+
## Release Checklist
133+
134+
Before each release:
135+
136+
- [ ] Update version in `package.json`
137+
- [ ] Update `CHANGELOG.md` with new version section
138+
- [ ] Review commit messages since last release
139+
- [ ] Test extension locally (`F5` in VSCode)
140+
- [ ] Run `npm run compile` to check for errors
141+
- [ ] Run `npm run test:unit` to verify tests pass
142+
- [ ] Commit version changes
143+
- [ ] Push to main (triggers automatic release)
144+
- [ ] Verify release created on GitHub
145+
- [ ] Download and test the VSIX artifact
146+
147+
## Files Involved
148+
149+
- `.releaserc.json` - Current config (no-commit mode)
150+
- `.releaserc.with-commit.json` - Alternative config (with commits)
151+
- `.github/workflows/release.yml` - Release workflow
152+
- `package.json` - Version number (manual updates)
153+
- `CHANGELOG.md` - Release notes (manual updates)
154+
155+
## Troubleshooting
156+
157+
### Release not created
158+
159+
Check:
160+
161+
1. Commits use conventional commit format
162+
2. There are unreleased changes since last tag
163+
3. Version in package.json is different from last release
164+
165+
### Wrong version in release
166+
167+
The version comes from `package.json`, not from commits. Make sure to update it before pushing.
168+
169+
### VSIX not attached
170+
171+
Check the workflow logs. The VSIX build happens before semantic-release, so if it fails, check the build logs.
172+
173+
## References
174+
175+
- [Semantic Release](https://semantic-release.gitbook.io/)
176+
- [Conventional Commits](https://www.conventionalcommits.org/)
177+
- [Semantic Versioning](https://semver.org/)
178+
- [VSCE Publishing](https://code.visualstudio.com/api/working-with-extensions/publishing-extension)

0 commit comments

Comments
 (0)