Skip to content

Commit 8350768

Browse files
committed
docs: document the release process and group release notes by label
Add RELEASING.md with the steps for the Python package, the VS Code extension and the shared web package, and link it from CONTRIBUTING.md. Add .github/release.yml so generated release notes list breaking changes and dependency updates in their own sections. Signed-off-by: mday-io <mdaytn@gmail.com>
1 parent 5a09168 commit 8350768

3 files changed

Lines changed: 84 additions & 0 deletions

File tree

‎.github/release.yml‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
# Groups the notes that GitHub generates for each release. See RELEASING.md.
2+
changelog:
3+
categories:
4+
- title: Breaking changes
5+
labels:
6+
- breaking-change
7+
- title: Dependencies
8+
labels:
9+
- dependencies
10+
- title: Other changes
11+
labels:
12+
- "*"

‎CONTRIBUTING.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -87,6 +87,10 @@ Optionally, `make install-pre-commit` installs git hooks so ruff and mypy run on
8787
- Include a DCO sign-off on all commits (`git commit -s`)
8888
- Be responsive to review feedback from maintainers
8989

90+
## Releases
91+
92+
Maintainers publish releases. See [RELEASING.md](RELEASING.md) for the steps.
93+
9094
## Licensing
9195

9296
Code contributions are licensed under the [Apache License 2.0](LICENSE). Documentation contributions are licensed under [Creative Commons Attribution 4.0 International (CC-BY-4.0)](https://creativecommons.org/licenses/by/4.0/). See the LICENSE file and the [technical charter](sqlmesh-technical-charter.pdf) for details.

‎RELEASING.md‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
# Releasing SQLMesh
2+
3+
This guide is for maintainers with write access to `SQLMesh/sqlmesh`. It covers the three things the project publishes:
4+
5+
| Package | Registry | How a release starts |
6+
|---|---|---|
7+
| `sqlmesh` (Python) | PyPI | Push a `v*.*.*` tag |
8+
| SQLMesh VS Code extension | VS Code Marketplace and Open VSX | Run the **Release VSCode Extension** workflow |
9+
| `@tobikodata/sqlmesh-common` | npm | Run the **Release web common code** workflow |
10+
11+
## Release the Python Package
12+
13+
The [`Release`](.github/workflows/release.yaml) workflow runs when a tag that matches `v*.*.*` is pushed. The package version comes from the tag through `setuptools_scm`, so you don't edit a version number in the code.
14+
15+
The workflow does four things:
16+
17+
1. Builds the web UI and bundles it into the package.
18+
2. Publishes `sqlmesh` to PyPI with `make publish`.
19+
3. Publishes the test package to the private `tobiko-private` registry with `make publish-tests`.
20+
4. Creates a GitHub release with notes generated from the pull requests merged since the previous tag.
21+
22+
Each step publishes immediately and there's no approval gate. Check `main` before you tag.
23+
24+
### Steps
25+
26+
1. Pick the commit to release. It must be on `main`, and every required check must pass on it. Check the latest **pr.yaml** run for that commit on the [Actions page](https://github.com/SQLMesh/sqlmesh/actions/workflows/pr.yaml).
27+
2. Pick the version. Find the latest tag with `git tag --sort=-creatordate | head -1` and increment it.
28+
3. Tag the commit and push the tag:
29+
30+
```bash
31+
git fetch <sqlmesh-remote> main --tags
32+
git tag v0.236.5 <commit-sha>
33+
git push <sqlmesh-remote> v0.236.5
34+
```
35+
36+
Replace `<sqlmesh-remote>` with your remote for `SQLMesh/sqlmesh`. Push only the tag, not a branch.
37+
38+
4. Watch the [Release](https://github.com/SQLMesh/sqlmesh/actions/workflows/release.yaml) run until it finishes.
39+
5. Check that the new version is on [PyPI](https://pypi.org/project/sqlmesh/#history).
40+
6. Edit the generated GitHub release. Under **Breaking changes**, add a short upgrade note for each entry. Say what users will see after upgrading, such as a migration or a metadata-only change in `sqlmesh plan`.
41+
42+
If the workflow fails after the PyPI step, don't delete or reuse the tag. PyPI doesn't accept the same version twice. Fix the cause and release the next version.
43+
44+
### Release Notes
45+
46+
GitHub builds the notes from merged pull request titles and groups them by label, as configured in [`.github/release.yml`](.github/release.yml):
47+
48+
| Label | Section |
49+
|---|---|
50+
| `breaking-change` | Breaking changes |
51+
| `dependencies` | Dependencies |
52+
| Any other label, or none | Other changes |
53+
54+
Dependabot adds `dependencies` automatically. Add `breaking-change` by hand to any pull request whose title has a `!`, such as `fix!:` or `feat!:`, before it merges. Without the label, the change appears under **Other changes**.
55+
56+
## Release the VS Code Extension
57+
58+
The [Release VSCode Extension](.github/workflows/release_extension.yaml) workflow publishes to the VS Code Marketplace and to Open VSX.
59+
60+
1. On the workflow's page, choose **Run workflow**.
61+
2. Select the `main` branch. The workflow stops if you run it from any other branch.
62+
3. Enter the version without a `v`, for example `0.0.8`.
63+
64+
The workflow sets the version only in its own build. It doesn't commit it, so `vscode/extension/package.json` keeps its old version. Check the [Marketplace listing](https://marketplace.visualstudio.com/items?itemName=tobikodata.sqlmesh) for the latest published version and enter a higher one.
65+
66+
## Release the Shared Web Package
67+
68+
The [Release web common code](.github/workflows/release_shared_js.yaml) workflow publishes `@tobikodata/sqlmesh-common` from `web/common` to npm. Run it the same way as the extension workflow: from `main`, with a version that has no `v`. It also doesn't commit the version, so check [npm](https://www.npmjs.com/package/@tobikodata/sqlmesh-common) for the latest published version first.

0 commit comments

Comments
 (0)