# 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).

```bash
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

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

### Convert GitHub-Flavored Markdown to Mkdocs

```bash
uv run docs/processor.py
```

## Update CHANGELOG

Ensure the [CHANGELOG](CHANGELOG.md) 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](#choosing-the-next-version-number) 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](https://github.com/mbarkhau/bumpver) 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:

```bash
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:

```bash
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:

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

### Choosing the Next Version Number

We try our best to adhere to [Semantic Versioning](https://semver.org/), 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`

```bash
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

```bash
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:

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

### Using Web

Draft a [new release](https://github.com/joshuadavidthomas/django-language-server/releases/new) 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.