Skip to content

Commit 3e129f7

Browse files
bpringebpringe
committed
Document release process in RELEASE.md
1 parent a2fdad7 commit 3e129f7

1 file changed

Lines changed: 195 additions & 0 deletions

File tree

‎docs/RELEASE.md‎

Lines changed: 195 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,195 @@
1+
# Calva Release Process
2+
3+
This document describes the Calva release process, including the happy path and troubleshooting common issues.
4+
5+
## Overview
6+
7+
Calva releases are automated through CircleCI. The release process is triggered by pushing a version tag to the repository. The tag format determines whether it's a pre-release or a stable release:
8+
9+
- **Pre-release**: `v2.0.560-dev`, `v2.0.560-rc1`, etc. (any suffix after the version)
10+
- **Stable release**: `v2.0.560` (semver only, no suffix)
11+
12+
Pre-releases are published only to GitHub Releases. Stable releases are published to:
13+
14+
- GitHub Releases
15+
- VS Code Marketplace
16+
- Open VSX Registry
17+
18+
## Prerequisites
19+
20+
- You must be on the `dev` branch
21+
- Your branch must be clean (no uncommitted changes)
22+
- Your branch must be up-to-date with remote
23+
- There should be unreleased changes in the changelog (otherwise you'll be prompted)
24+
- [Babashka](https://babashka.org/) must be installed
25+
26+
## The Happy Path
27+
28+
### 1. Verify Changelog Entries
29+
30+
Before releasing, ensure all changes are documented in the `## [Unreleased]` section of `CHANGELOG.md`. Each entry should follow the format:
31+
32+
```markdown
33+
- Fix: [Issue title](https://github.com/BetterThanTomorrow/calva/issues/XXXX)
34+
- [Feature description](https://github.com/BetterThanTomorrow/calva/issues/XXXX)
35+
```
36+
37+
Use the "Fix:" prefix only for bug fixes.
38+
39+
### 2. Verify Version in package.json
40+
41+
The version in `package.json` should already be set to the next release version (this is done automatically after each release by the CI pipeline).
42+
43+
### 3. Run the Publish Script
44+
45+
From the repository root, run:
46+
47+
```bash
48+
npm run publish
49+
```
50+
51+
Or directly:
52+
53+
```bash
54+
./scripts/publish.clj
55+
```
56+
57+
You can also add an optional commit message suffix:
58+
59+
```bash
60+
./scripts/publish.clj "Co-authored-by: Someone <someone@example.com>"
61+
```
62+
63+
The script will:
64+
65+
1. Verify you're on `dev` branch, clean, and up-to-date
66+
2. Read the current version from `package.json`
67+
3. Update `CHANGELOG.md` to move unreleased changes under a dated version header
68+
4. Commit the changelog with message: `Add changelog section for vX.Y.Z [skip ci]`
69+
5. Create a git tag: `vX.Y.Z`
70+
6. Push the commit and tag to the remote
71+
72+
### 4. Monitor CI Pipeline
73+
74+
After pushing, open the [CircleCI dashboard](https://app.circleci.com/pipelines/github/BetterThanTomorrow/calva) to monitor progress.
75+
76+
The CI pipeline will:
77+
78+
1. Run all tests (prettier, eslint, grammar, ClojureScript lib, integration, E2E, TypeScript unit)
79+
2. Create a GitHub Release with the changelog contents
80+
3. For stable releases:
81+
- Publish to VS Code Marketplace
82+
- Publish to Open VSX Registry
83+
- Merge `dev` into `published` branch
84+
- Bump the version in `package.json` on `dev` for the next release
85+
86+
### 5. Verify the Release
87+
88+
After CI completes:
89+
90+
- Check [GitHub Releases](https://github.com/BetterThanTomorrow/calva/releases) for the new release
91+
- For stable releases, verify the extension is available on:
92+
- [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=betterthantomorrow.calva)
93+
- [Open VSX Registry](https://open-vsx.org/extension/betterthantomorrow/calva)
94+
95+
## Troubleshooting
96+
97+
### Tests Fail After Publish Script Succeeds
98+
99+
If the publish script completes successfully but tests fail in CI:
100+
101+
1. **Revert the changelog commit:**
102+
103+
```bash
104+
git revert HEAD
105+
git push
106+
```
107+
108+
2. **Delete the version tag locally and remotely:**
109+
110+
```bash
111+
git tag -d vX.Y.Z
112+
git push origin :refs/tags/vX.Y.Z
113+
```
114+
115+
3. Fix the failing tests, then run the publish script again.
116+
117+
### "Merge published into dev" Step Fails
118+
119+
If the `calva-io-build` workflow's "Merge published into dev" step fails with:
120+
121+
```bash
122+
! [rejected] HEAD -> dev (non-fast-forward)
123+
error: failed to push some refs to 'git@github.com:BetterThanTomorrow/calva.git'
124+
hint: Updates were rejected because the tip of your current branch is behind
125+
hint: its remote counterpart. Integrate the remote changes (e.g.
126+
hint: 'git pull ...') before pushing again.
127+
```
128+
129+
This happens when `dev` has new commits since the release was tagged. Resolve it manually:
130+
131+
```bash
132+
git checkout dev
133+
git pull
134+
git merge origin/published --no-ff -m "Merge branch published into dev [skip ci]"
135+
git push
136+
```
137+
138+
### Publish Script Aborts Due to Git Status
139+
140+
If the publish script reports git status issues, you'll see messages like:
141+
142+
- `:not-on-dev` - You're not on the `dev` branch
143+
- `:not-up-to-date` - Your local branch is behind remote
144+
- `:branch-not-clean` - You have uncommitted changes
145+
146+
Resolve the specific issue and run the script again.
147+
148+
### Empty Unreleased Changelog
149+
150+
If the changelog has no unreleased changes, the script will ask if you want to release anyway. Answering `YES` will:
151+
152+
- Skip the changelog update
153+
- Create a tag and push (useful for re-releasing after a failed CI run)
154+
155+
## Pre-releases
156+
157+
Pre-releases are useful for testing changes before a stable release. To create a pre-release:
158+
159+
1. Manually edit `package.json` to add a suffix to the version (e.g., `2.0.561-rc1`)
160+
2. Run the publish script
161+
162+
Pre-releases:
163+
164+
- Are published only to GitHub Releases (not marketplaces)
165+
- Do not trigger the `merge-dev-into-published` or `bump-dev-version` jobs
166+
- Allow early adopters to test via `.vsix` download from GitHub
167+
168+
## CI Workflow Details
169+
170+
### release-publish Workflow
171+
172+
Triggered by version tags (`v*`). Jobs run in this order:
173+
174+
1. **checkout** - Clone repository
175+
2. **build** - Build the extension
176+
3. **Tests** (parallel): prettier-check, eslint-check, test-grammar, test-cljslib, test-integration, test-e2e, test-e2e-sub-projects, test-ts-unit
177+
4. **github-release** - Create GitHub release with `.vsix` artifact
178+
5. **marketplace-publish** - Publish to VS Code Marketplace (stable only)
179+
6. **open-vsx-publish** - Publish to Open VSX (stable only)
180+
7. **merge-dev-into-published** - Merge `dev` branch into `published` (stable only)
181+
8. **bump-dev-version** - Increment patch version on `dev` (stable only)
182+
183+
### calva-io-build Workflow
184+
185+
Triggered by pushes to `published` branch:
186+
187+
1. **deploy-docs** - Deploy documentation to calva.io
188+
2. **merge-published-into-dev** - Merge `published` back into `dev`
189+
190+
## Branch Strategy
191+
192+
- **dev**: Main development branch. All feature branches merge here.
193+
- **published**: Reflects the latest stable release. Updated automatically after stable releases.
194+
195+
Documentation PRs that only update the `docs/site/` content should target the `published` branch directly.

0 commit comments

Comments
 (0)