Skip to content

Release Checklist

This document is intended for app maintainers and covers the steps to perform when releasing new versions of the app.

Important

Before starting, make sure your local develop, main, and (if applicable) the current LTM branch are all up to date with upstream!

git fetch
git switch develop && git pull # and repeat for main/ltm

Minor Version Bumps

Update Requirements

Every minor version release should refresh poetry.lock, so that it lists the most recent stable release of each package. To do this:

  1. Run poetry update --dry-run to have Poetry automatically tell you what package updates are available and the versions it would upgrade to. This requires an existing environment created from the lock file (i.e. via poetry install).
  2. Review each requirement's release notes for any breaking or otherwise noteworthy changes.
  3. Run poetry update <package> to update the package versions in poetry.lock as appropriate.
  4. If a required package requires updating to a new release not covered in the version constraints for a package as defined in pyproject.toml, (e.g. Django ~3.1.7 would never install Django >=4.0.0), update it manually in pyproject.toml.
  5. Run poetry install to install the refreshed versions of all required packages.
  6. Run all tests (poetry run invoke tests) and check that the UI and API function as expected.

Update Documentation

Commit any resulting changes from the following sections to the documentation before proceeding with the release.

Tip

Fire up the documentation server in your development environment with poetry run mkdocs serve! This allows you to view the documentation site locally (the link is in the output of the command) and automatically rebuilds it as you make changes.

Verify the Installation and Upgrade Steps

Follow the installation instructions to perform a new production installation of the app. If possible, also test the upgrade process from the previous released version.

The goal of this step is to walk through the entire install process as documented to make sure nothing there needs to be changed or updated, to catch any errors or omissions in the documentation, and to ensure that it is current with each release.


All Releases

Verify CI Build Status

Ensure that continuous integration testing on the develop branch is completing successfully.

Bump the Version

Update the package version using poetry version if necessary. This command shows the current version of the project or bumps the version of the project and writes the new version back to pyproject.toml if a valid bump rule is provided.

The new version must be a valid semver string or a valid bump rule: patch, minor, major, prepatch, preminor, premajor, prerelease. Always try to use a bump rule when you can.

Display the current version with no arguments:

> poetry version
nautobot-dev-example 1.0.0-beta.2

Bump pre-release versions using prerelease:

> poetry version prerelease
Bumping version from 1.0.0-beta.2 to 1.0.0-beta.3

For major versions, use major:

> poetry version major
Bumping version from 1.0.0-beta.2 to 1.0.0

For patch versions, use minor:

> poetry version minor
Bumping version from 1.0.0 to 1.1.0

And lastly, for patch versions, you guessed it, use patch:

> poetry version patch
Bumping version from 1.1.0 to 1.1.1

Please see the official Poetry documentation on version for more information.

Update the Changelog

Important

The changelog must adhere to the Keep a Changelog style guide.

This guide uses 1.4.2 as the new version in its examples, so change it to match the version you bumped to in the previous step! Every. single. time. you. copy/paste commands :)

First, create a release branch off of develop (git switch -c release-1.4.2 develop).

You will need to have the project's poetry environment built at this stage, as the towncrier command runs locally only. If you don't have it, run poetry install first.

Generate release notes with invoke generate-release-notes --version 1.4.2 and answer yes to the prompt Is it okay if I remove those files? [Y/n]:. This will update the release notes in docs/admin/release_notes/version_X.Y.md, stage that file in git, and git rm all the fragments that have now been incorporated into the release notes.

There are two possibilities:

  1. If you're releasing a new major or minor version, rename the version_X.Y.md file accordingly (e.g. rename to docs/admin/release_notes/version_1.4.md). Update the Release Overview and add this new page to the table of contents within mkdocs.yml.
  2. If you're releasing a patch version, copy your version's section from the version_X.Y.md file into the already existing docs/admin/release_notes/version_1.4.md file. Delete the version_X.Y.md file.

Check the git diff to verify the changes are correct (git diff --cached). Remember to also run git add pyproject.toml to stage the version bump.

Commit git commit -m "Create release v1.4.2" and push the staged changes.

Submit Release Pull Request

Submit a pull request titled Release v1.4.2 to merge your release branch into main. Copy the documented release notes into the pull request's body.

Once CI has completed on the PR, merge it.

Important

Do not squash merge this branch into main. Make sure to select Create a merge commit when merging in GitHub.

Create a New Release in GitHub

Draft a new release with the following parameters.

  • Tag: Input current version (e.g. v1.4.2) and select Create new tag: v1.4.2 on publish
  • Target: main
  • Title: Version and date (e.g. v1.4.2 - 2024-04-02)

Click "Generate Release Notes" and edit the auto-generated content as follows:

  • Change the entries generated by GitHub to only the usernames of the contributors. e.g. * Updated dockerfile by @nautobot_user in https://github.com/nautobot/nautobot/pull/123 -> * @nautobot_user.
    • This should give you the list for the new Contributors section.
    • Make sure there are no duplicated entries.
  • Replace the content of the What's Changed section with the description of changes from the release PR (what towncrier generated).
  • Leave the New Contributors list as it is.

The release notes should look as follows:

## What's Changed

**Towncrier generated Changed/Fixed/Housekeeping etc. sections here**

## Contributors

* @alice
* @bob

## New Contributors

* @bob

Publish the release!

Create a PR from main back to develop

First, sync your main branch with upstream changes: git switch main && git pull.

Create a new branch from main called release-1.4.2-to-develop and use poetry version prepatch to bump the development version to the next release.

For example, if you just released v1.4.2:

> git switch -c release-1.4.2-to-develop main
Switched to a new branch 'release-1.4.2-to-develop'

> poetry version prepatch
Bumping version from 1.4.2 to 1.4.3a1

> git commit -m "Bump version"

Open a new PR from release-1.4.2-to-develop against develop, wait for CI to pass, and merge it.

Important

Do not squash merge this branch into develop. Make sure to select Create a merge commit when merging in GitHub.