django-language-server/RELEASING.md

Releasing a New Version

Create Release Branch

Create a new git branch off of main for the release.

The name should follow the naming convention release/<version>, where <version> is the next incremental version number (e.g. release/v0.1.0 for version 0.1.0).

git checkout -b release/v<version>

By default, only a subset of the test suite runs on PRs. Any branch named with the prefix release/* will trigger the full test suite to run.

Update Documentation

Run cog

uv run --with bumpver --with cogapp --with nox cog -r <COG_FILES>

Convert GitHub-Flavored Markdown to Mkdocs

uv run docs/processor.py

Update CHANGELOG

Ensure the CHANGELOG is up to date. If updates are needed, add them now in the release branch.

Bump Version Number

Update the version number across the project using the bumpver tool. See this section for more details about choosing the correct version number.

The pyproject.toml in the base of the repository contains a [tool.bumpver] section that configures the bumpver tool to update the version number wherever it needs to be updated and to create a commit with the appropriate commit message.

Run bumpver to update the version number, with the appropriate command line arguments. See the bumpver documentation for more details.

Note: For any of the following commands, you can add the command line flag --dry to preview the changes without actually making the changes.

Here are the most common commands you will need to run:

uv run --with bumpver bumpver update --patch  # for a patch release
uv run --with bumpver bumpver update --minor  # for a minor release
uv run --with bumpver bumpver update --major  # for a major release

To release a tagged version, such as a beta or release candidate, you can run:

uv run --with bumpver bumpver update --tag=beta
# or
uv run --with bumpver bumpver update --tag=rc

Running these commands on a tagged version will increment the tag appropriately, but will not increment the version number.

To go from a tagged release to a full release, you can run:

uv run --with bumpver bumpver update --tag=final

Choosing the Next Version Number

We try our best to adhere to Semantic Versioning, but we do not promise to follow it perfectly (and let's be honest, this is the case with a lot of projects using SemVer).

In general, use your best judgement when choosing the next version number. If you are unsure, you can always ask for a second opinion from another contributor.

Update uv.lock

uv lock

Create Release PR

Create a pull request from the release branch to main.

Once CI has passed and all the checks are green ✅, merge the pull request.

Create New GitHub Release

Using CLI

gh release create v<version> --generate-notes

If this is a tagged version (e.g. alpha or beta), make sure to call the create command with the --prerelease flag:

gh release create v0.0.0a0 --generate-notes --prerelease

Using Web

Draft a new release on GitHub.

Use the version number with a leading v as the tag name (e.g. v0.1.0).

Allow GitHub to generate the release title and release notes, using the 'Generate release notes' button above the text box.

If this is a tagged version (e.g. alpha or beta), make sure to check the 'Set as a pre-release' checkbox.

Publish to PyPI

Once a GitHub release has been published, GitHub will automatically run the full test suite, including building the package against all supported OSes, Python and Django versions. Once this test suite run passes, a GitHub Actions job will publish the new version of the package to PyPI.