Home

Release process

Pre-requisites

In order for this process to work, you should clone Narwhals locally using ssh.

Then, run verify that you see the following output if you run git remote get-url upstream:

$ git remote get-url upstream
git@github.com:narwhals-dev/narwhals.git

If not, then you should first do

git remote add upstream git@github.com:narwhals-dev/narwhals.git

Fetch the latest changes

After you've merged everything you'd like to include, please make sure you're up-to-date with upstream/main:

git checkout main
git fetch upstream
git reset --hard upstream/main

Release process

1. Copy/fixup the release notes: go to https://github.com/narwhals-dev/narwhals/releases, click "edit" on the latest (draft) release notes. If anything needs fixing up, you can do so now. Once you're done, copy all the content, and paste it somewhere. You'll need this later.
2. Make sure that bump-version branch doesn't appear in https://github.com/narwhals-dev/narwhals/branches - if it does, delete it.
3. Make a new bump-version branch: git checkout -b bump-version
4. Run python utils/bump_version.py patch. Replace 'patch' with either 'minor' or 'major', depending on by how much you want to bump the version. In general, we try to mirror Polars release for major and minor versions, but not for patch versions - so:
   • if the latest Polars release is 3.4.2 and the latest Narwhals release is 3.3.4, you should bump Narwhals to 3.4.0
   • if the latest Polars release is 3.4.2 and the latest Narwhals release is 3.4.5, you should bump Narwhals to 3.4.6
   • if the latest Polars release is 4.0.1 and the latest Narwhals release is 3.4.5, you should bump Narwhals to 4.0.0
5. Open a pull request from bump-version to main. To do this, go to https://github.com/narwhals-dev/narwhals/pulls, click "new pull request", and open a pull request from bump-version to main. Set the "release" label.
6. Go to the latest published release in https://github.com/narwhals-dev/narwhals/releases. You will probably see "Narwhals Unreleased" in draft (with full release notes), and something like v3.1.4 as published (without any release notes). Copy the "Narwhals Unreleased" release notes into the v3.1.4 release notes, and amend the title to be of the form "Narhwals v<version goes here>", e.g. Narwhals v3.1.4. Do not click "publish" on the "Narwhals Unreleased" notes.
7. After you've published the release notes, merge the PR from bump-version to main.

NOTE: if you see a message like bypassed rule violations, don't worry about it - we block people from creating tags (as they trigger releases) so if you see it, it's because you have permission to bypass that rule 😇