|
| 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 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`. |
| 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). The [PR Labels](.github/workflows/pr-labels.yaml) workflow applies the labels from each pull request's title (`type(scope): description`), and adds `migration` to pull requests that add a state migration. See [Pull Request Titles](CONTRIBUTING.md#pull-request-titles) in `CONTRIBUTING.md`. |
| 47 | +
|
| 48 | +- A `!` in the title, such as `fix!:` or `feat!:`, puts the pull request under **Breaking changes**. |
| 49 | +- A pull request that adds a state migration goes under **State migrations**. |
| 50 | +- CI, test and Dependabot pull requests are left out. Add the `skip-changelog` label to leave out any other pull request. |
| 51 | +
|
| 52 | +To move a pull request to another section, change its title. The workflow resets the type labels from the title. |
| 53 | +
|
| 54 | +## Release the VS Code Extension |
| 55 | +
|
| 56 | +The [Release VSCode Extension](.github/workflows/release_extension.yaml) workflow publishes to the VS Code Marketplace and to Open VSX. |
| 57 | +
|
| 58 | +1. On the workflow's page, choose **Run workflow**. |
| 59 | +2. Select the `main` branch. The workflow stops if you run it from any other branch. |
| 60 | +3. Enter the version without a `v`, for example `0.0.8`. |
| 61 | + |
| 62 | +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. |
| 63 | +
|
| 64 | +## Release the Shared Web Package |
| 65 | +
|
| 66 | +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