From 83507680f75e760d14269b609bf1fe6949ee077b Mon Sep 17 00:00:00 2001 From: mday-io Date: Sun, 1 Nov 2026 22:05:29 +0000 Subject: [PATCH 1/2] 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 --- .github/release.yml | 12 ++++++++ CONTRIBUTING.md | 4 +++ RELEASING.md | 68 +++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 84 insertions(+) create mode 100644 .github/release.yml create mode 100644 RELEASING.md diff --git a/.github/release.yml b/.github/release.yml new file mode 100644 index 0000000000..9d86bd7c1d --- /dev/null +++ b/.github/release.yml @@ -0,0 +1,12 @@ +# Groups the notes that GitHub generates for each release. See RELEASING.md. +changelog: + categories: + - title: Breaking changes + labels: + - breaking-change + - title: Dependencies + labels: + - dependencies + - title: Other changes + labels: + - "*" diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4533069d5c..6e6d99cc4e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -87,6 +87,10 @@ Optionally, `make install-pre-commit` installs git hooks so ruff and mypy run on - Include a DCO sign-off on all commits (`git commit -s`) - Be responsive to review feedback from maintainers +## Releases + +Maintainers publish releases. See [RELEASING.md](RELEASING.md) for the steps. + ## Licensing 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. diff --git a/RELEASING.md b/RELEASING.md new file mode 100644 index 0000000000..727225d0c3 --- /dev/null +++ b/RELEASING.md @@ -0,0 +1,68 @@ +# Releasing SQLMesh + +This guide is for maintainers with write access to `SQLMesh/sqlmesh`. It covers the three things the project publishes: + +| Package | Registry | How a release starts | +|---|---|---| +| `sqlmesh` (Python) | PyPI | Push a `v*.*.*` tag | +| SQLMesh VS Code extension | VS Code Marketplace and Open VSX | Run the **Release VSCode Extension** workflow | +| `@tobikodata/sqlmesh-common` | npm | Run the **Release web common code** workflow | + +## Release the Python Package + +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. + +The workflow does four things: + +1. Builds the web UI and bundles it into the package. +2. Publishes `sqlmesh` to PyPI with `make publish`. +3. Publishes the test package to the private `tobiko-private` registry with `make publish-tests`. +4. Creates a GitHub release with notes generated from the pull requests merged since the previous tag. + +Each step publishes immediately and there's no approval gate. Check `main` before you tag. + +### Steps + +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). +2. Pick the version. Find the latest tag with `git tag --sort=-creatordate | head -1` and increment it. +3. Tag the commit and push the tag: + + ```bash + git fetch main --tags + git tag v0.236.5 + git push v0.236.5 + ``` + + Replace `` with your remote for `SQLMesh/sqlmesh`. Push only the tag, not a branch. + +4. Watch the [Release](https://github.com/SQLMesh/sqlmesh/actions/workflows/release.yaml) run until it finishes. +5. Check that the new version is on [PyPI](https://pypi.org/project/sqlmesh/#history). +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`. + +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. + +### Release Notes + +GitHub builds the notes from merged pull request titles and groups them by label, as configured in [`.github/release.yml`](.github/release.yml): + +| Label | Section | +|---|---| +| `breaking-change` | Breaking changes | +| `dependencies` | Dependencies | +| Any other label, or none | Other changes | + +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**. + +## Release the VS Code Extension + +The [Release VSCode Extension](.github/workflows/release_extension.yaml) workflow publishes to the VS Code Marketplace and to Open VSX. + +1. On the workflow's page, choose **Run workflow**. +2. Select the `main` branch. The workflow stops if you run it from any other branch. +3. Enter the version without a `v`, for example `0.0.8`. + +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. + +## Release the Shared Web Package + +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. From ce272ae0dad5126e2b4f1371ed32fb494ad983cb Mon Sep 17 00:00:00 2001 From: mday-io Date: Sun, 1 Nov 2026 22:12:49 +0000 Subject: [PATCH 2/2] docs: describe release notes from SQLMesh/sqlmesh#6178 #6178 adds .github/release.yml with labels applied automatically from PR titles, and creates GitHub releases as drafts. Drop this PR's simpler release.yml so the two don't conflict, and update RELEASING.md to match: labels come from the title, and the release step is to edit and publish the draft. Move the Releases section to the end of CONTRIBUTING.md so it doesn't conflict with the PR title section #6178 adds. Signed-off-by: mday-io --- .github/release.yml | 12 ------------ CONTRIBUTING.md | 8 ++++---- RELEASING.md | 18 ++++++++---------- 3 files changed, 12 insertions(+), 26 deletions(-) delete mode 100644 .github/release.yml diff --git a/.github/release.yml b/.github/release.yml deleted file mode 100644 index 9d86bd7c1d..0000000000 --- a/.github/release.yml +++ /dev/null @@ -1,12 +0,0 @@ -# Groups the notes that GitHub generates for each release. See RELEASING.md. -changelog: - categories: - - title: Breaking changes - labels: - - breaking-change - - title: Dependencies - labels: - - dependencies - - title: Other changes - labels: - - "*" diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6e6d99cc4e..4c46ed996c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -87,10 +87,10 @@ Optionally, `make install-pre-commit` installs git hooks so ruff and mypy run on - Include a DCO sign-off on all commits (`git commit -s`) - Be responsive to review feedback from maintainers -## Releases - -Maintainers publish releases. See [RELEASING.md](RELEASING.md) for the steps. - ## Licensing 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. + +## Releases + +Maintainers publish releases. See [RELEASING.md](RELEASING.md) for the steps. diff --git a/RELEASING.md b/RELEASING.md index 727225d0c3..fff4c38fe9 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -17,9 +17,9 @@ The workflow does four things: 1. Builds the web UI and bundles it into the package. 2. Publishes `sqlmesh` to PyPI with `make publish`. 3. Publishes the test package to the private `tobiko-private` registry with `make publish-tests`. -4. Creates a GitHub release with notes generated from the pull requests merged since the previous tag. +4. Creates a draft GitHub release with notes generated from the pull requests merged since the previous tag. -Each step publishes immediately and there's no approval gate. Check `main` before you tag. +The PyPI and private registry uploads happen immediately, with no approval gate. Check `main` before you tag. ### Steps @@ -37,21 +37,19 @@ Each step publishes immediately and there's no approval gate. Check `main` befor 4. Watch the [Release](https://github.com/SQLMesh/sqlmesh/actions/workflows/release.yaml) run until it finishes. 5. Check that the new version is on [PyPI](https://pypi.org/project/sqlmesh/#history). -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`. +6. Open the draft release on the [Releases page](https://github.com/SQLMesh/sqlmesh/releases). 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`. Then publish it. Until you do, no GitHub release appears for the version, even though it's on PyPI. 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. ### Release Notes -GitHub builds the notes from merged pull request titles and groups them by label, as configured in [`.github/release.yml`](.github/release.yml): +GitHub builds the notes from merged pull request titles and groups them by label, as configured in [`.github/release.yml`](.github/release.yml). The [PR Labels](.github/workflows/pr-labels.yaml) workflow applies the labels from each pull request's title (`type(scope): description`) and the files it changes. See [Pull Request Titles](CONTRIBUTING.md#pull-request-titles) in `CONTRIBUTING.md`. -| Label | Section | -|---|---| -| `breaking-change` | Breaking changes | -| `dependencies` | Dependencies | -| Any other label, or none | Other changes | +- A `!` in the title, such as `fix!:` or `feat!:`, puts the pull request under **Breaking changes**. +- A pull request that adds a state migration goes under **State migrations**. +- CI, test and Dependabot pull requests are left out. Add the `skip-changelog` label to leave out any other pull request. -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**. +To move a pull request to another section, change its title. The workflow resets the type labels from the title. ## Release the VS Code Extension