|
| 1 | +# Release Checklist |
| 2 | + |
| 3 | +This document is intended for cookie maintainers and outlines the steps to perform when releasing a new version of the cookie. |
| 4 | + |
| 5 | +!!! important |
| 6 | + Before starting, make sure your **local** `develop`, `main`, and (if applicable) the current LTM branch are all up to date with upstream! |
| 7 | + |
| 8 | + ``` |
| 9 | + git fetch |
| 10 | + git switch develop && git pull # and repeat for main/ltm |
| 11 | + ``` |
| 12 | + |
| 13 | +Choose your own adventure: |
| 14 | + |
| 15 | +- LTM release? Jump [here](#ltm-releases). |
| 16 | +- Patch release from `develop`? Jump [here](#all-releases-from-develop). |
| 17 | +- Minor release? Continue with [Minor Version Bumps](#minor-version-bumps) and then [All Releases from `develop`](#all-releases-from-develop). |
| 18 | + |
| 19 | +## Minor Version Bumps |
| 20 | + |
| 21 | +### Update Requirements |
| 22 | + |
| 23 | +Every minor version release should refresh `poetry.lock`, so that it lists the most recent stable release of each package. To do this: |
| 24 | + |
| 25 | +0. 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`). |
| 26 | +1. Review each requirement's release notes for any breaking or otherwise noteworthy changes. |
| 27 | +2. Run `poetry update <package>` to update the package versions in `poetry.lock` as appropriate. |
| 28 | +3. 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`. |
| 29 | +4. Run `poetry install` to install the refreshed versions of all required packages. |
| 30 | +5. Run all tests (`poetry run invoke tests`) and check that the UI and API function as expected. |
| 31 | + |
| 32 | +### Update Documentation |
| 33 | + |
| 34 | +If there are any changes to the compatibility matrix (such as a bump in the minimum supported Nautobot version), update it accordingly. |
| 35 | + |
| 36 | +Commit any resulting changes from the following sections to the documentation before proceeding with the release. |
| 37 | + |
| 38 | +!!! tip |
| 39 | + 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. |
| 40 | + |
| 41 | +### Create Release Notes |
| 42 | + |
| 43 | +For every minor version, we need to create a new release notes file, update `tool.towncrier.filename` in `pyproject.toml` and update the `mkdocs.yml` table of contents. |
| 44 | + |
| 45 | +The new release notes file should be named `version_<major>.<minor>.md` (e.g. `version_2.7.md`) and placed in the `docs/admin/release_notes/` directory. The easiest way to create this file is to copy the most recent existing version (e.g. `version_2.6.md`) and then delete anything after the `<!-- towncrier release notes start -->` line. Update the rest of the copied content to reflect the new version number and release overview section. |
| 46 | + |
| 47 | +Find the `tool.towncrier` section in `pyproject.toml` and update the `filename` value to match the new release notes file you just created. |
| 48 | + |
| 49 | +Finally, open `mkdocs.yml` and add an entry for the new release notes file in the table of contents under `nav`.`Administrator Guide`.`Release Notes`. |
| 50 | + |
| 51 | +### Verify the Cookie Outputs Valid Code |
| 52 | + |
| 53 | +Follow the [usage instructions](https://github.com/nautobot/cookiecutter-nautobot-app/#usage-with-cookiecutter) to bake a new cookie. If possible run `invoke tests` in the newly created app to verify that the cookie outputs valid code. |
| 54 | + |
| 55 | +--- |
| 56 | + |
| 57 | +## All Releases from `develop` |
| 58 | + |
| 59 | +### Verify CI Build Status |
| 60 | + |
| 61 | +Ensure that continuous integration testing on the `develop` branch is completing successfully. |
| 62 | + |
| 63 | +### Update the Changelog |
| 64 | + |
| 65 | +!!! important |
| 66 | + The changelog must adhere to the [Keep a Changelog](https://keepachangelog.com/) style guide. |
| 67 | + |
| 68 | +This guide uses `nautobot-app-v2.7.0` as the new version in its examples, so change it to match the version you wish to use! Every. single. time. you. copy/paste commands :) |
| 69 | + |
| 70 | +First, create a release branch off of `develop` (`git switch -c release-nautobot-app-2.7.0 develop`). |
| 71 | + |
| 72 | +> 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. |
| 73 | +
|
| 74 | +Generate release notes with `invoke generate-release-notes --version nautobot-app-v2.7.0` 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_2.7.md`, stage that file in git, and `git rm` all the fragments that have now been incorporated into the release notes. |
| 75 | + |
| 76 | +Stage all the changes (`git add`) and check the diffs to verify all of the changes are correct (`git diff --cached`). |
| 77 | + |
| 78 | +Commit `git commit -m "Release nautobot-app-v2.7.0"` and `git push` the staged changes. |
| 79 | + |
| 80 | +### Submit Release Pull Request |
| 81 | + |
| 82 | +Submit a pull request titled `Release nautobot-app-v2.7.0` to merge your release branch into `main`. Copy the documented release notes into the pull request's body. |
| 83 | + |
| 84 | +!!! important |
| 85 | + Do not squash merge this branch into `main`. Make sure to select `Create a merge commit` when merging in GitHub. |
| 86 | + |
| 87 | +Once CI has completed on the PR, merge it. |
| 88 | + |
| 89 | +### Create a New Release in GitHub |
| 90 | + |
| 91 | +Draft a [new release]({{ cookiecutter.repo_url }}/releases/new) with the following parameters. |
| 92 | + |
| 93 | +* **Tag:** Input current version (e.g. `nautobot-app-v2.7.0`) and select `Create new tag: nautobot-app-v2.7.0 on publish` |
| 94 | +* **Target:** `main` |
| 95 | +* **Title:** Version and date (e.g. `nautobot-app-v2.7.0 - 2024-04-02`) |
| 96 | + |
| 97 | +Click "Generate Release Notes" and edit the auto-generated content as follows: |
| 98 | + |
| 99 | +- Change the entries generated by GitHub to only the usernames of the contributors. e.g. `* Updated dockerfile by @nautobot_user in {{ cookiecutter.repo_url }}/pull/123` -> `* @nautobot_user`. |
| 100 | + - This should give you the list for the new `Contributors` section. |
| 101 | + - Make sure there are no duplicated entries. |
| 102 | +- Replace the content of the `What's Changed` section with the description of changes from the release PR (what towncrier generated). |
| 103 | +- If it exists, leave the `New Contributors` list as it is. |
| 104 | + |
| 105 | +The release notes should look as follows: |
| 106 | + |
| 107 | +```markdown |
| 108 | +## What's Changed |
| 109 | + |
| 110 | +**Towncrier generated Changed/Fixed/Housekeeping etc. sections here** |
| 111 | + |
| 112 | +## Contributors |
| 113 | + |
| 114 | +* @alice |
| 115 | +* @bob |
| 116 | + |
| 117 | +## New Contributors |
| 118 | + |
| 119 | +* @bob |
| 120 | + |
| 121 | +**Full Changelog**: https://github.com/nautobot/cookiecutter-nautobot-app/compare/nautobot-app-v2.6.1...nautobot-app-v2.7.0 |
| 122 | +``` |
| 123 | + |
| 124 | +Publish the release! |
| 125 | + |
| 126 | +### Create a PR from `main` back to `develop` |
| 127 | + |
| 128 | +!!! note |
| 129 | + Since this project doesn't use poetry to maintain a python package, there is no need to bump a version in `pyproject.toml`. You can open a PR directly from `main` to `develop` in GitHub without creating a third branch. |
| 130 | + |
| 131 | +!!! important |
| 132 | + Do not squash merge this PR into `develop`. Make sure to select `Create a merge commit` when merging in GitHub. |
| 133 | + |
| 134 | +Open a new PR from `main` against `develop`, wait for CI to pass, and merge it. |
| 135 | + |
| 136 | +### Final checks |
| 137 | + |
| 138 | +At this stage, documentation should have been built for the tag on ReadTheDocs and if you're reading this page online, refresh it and look for the new version in the little version fly-out menu down at the bottom right of the page. |
| 139 | + |
| 140 | +All done! |
| 141 | + |
| 142 | +## LTM Releases |
| 143 | + |
| 144 | +For projects maintaining a Nautobot LTM compatible release, all development and release management is done through the `ltm-x.y` branch. The `x.y` relates to the LTM version of Nautobot it's compatible with, for example `1.6`. |
| 145 | + |
| 146 | +The process is similar to releasing from `develop`, but there is no need for post-release branch syncing because you'll release directly from the LTM branch: |
| 147 | + |
| 148 | +1. Make sure your `ltm-1.6` branch is passing CI. |
| 149 | +2. Create a release branch from the `ltm-1.6` branch: `git switch -c release-1.2.3 ltm-1.6`. |
| 150 | +3. Generate the release notes: `invoke generate-release-notes --version nautobot-app-v1.6.3`. |
| 151 | +4. Add all the changes and `git commit -m "Release v1.2.3"`, then `git push`. |
| 152 | +5. Open a new PR against `ltm-1.6`. Once CI is passing in the PR, merge it. |
| 153 | +6. Create a New Release in GitHub - use the same steps documented [here](#create-a-new-release-in-github). |
| 154 | +7. Open a separate PR against `develop` to synchronize all LTM release changelogs into the latest version of the docs for visibility. |
0 commit comments