Fix #120 - Revise development release checklist

nautobot/docs/development/release-checklist.md

@@ -1,50 +1,71 @@
 # Release Checklist
 
+This document is intended for Nautobot maintainers and covers the steps to perform when releasing new versions.
+
 ## Minor Version Bumps
 
 ### Update Requirements
 
-Required Python packages are maintained in two files. `base_requirements.txt` contains a list of all the packages required by Nautobot. Some of them may be pinned to a specific version of the package due to a known issue. For example:
+Required Python packages are maintained in two files: `pyproject.toml` and `poetry.lock`. 
+
+#### The `pyproject.toml` file
+Python packages are defined inside of `pyproject.toml`. The `[tool.poetry.dependencies]` section of this file contains a list of all the packages required by Nautobot.
+
+Where possible, we use [tilde requirements](https://python-poetry.org/docs/dependency-specification/#tilde-requirements) to specify a minimal version with some ability to update, for example:
 
 ```
-# https://github.com/encode/django-rest-framework/issues/6053
-djangorestframework==3.8.1
+# REST API framework
+djangorestframework = "~3.12.2"
 ```
 
-The other file is `requirements.txt`, which lists each of the required packages pinned to its current stable version. When Nautobot is installed, the Python environment is configured to match this file. This helps ensure that a new release of a dependency doesn't break Nautobot.
+This would allow Poetry to install `djangorestframework` versions `>=3.12.2` but `<3.13.0`.
+
+#### The `poetry.lock` file
+
+The other file is `poetry.lock`, which is managed by Poetry and contains package names, versions, and other metadata.
+
+Each of the required packages pinned to its current stable version. When Nautobot is installed, this file is used to resolve and install all dependencies listed in `pyproject.toml`, but Poetry will use the exact versions found in `poetry.lock` to ensure that a new release of a dependency doesn't break Nautobot.
 
-Every minor version release should refresh `requirements.txt` so that it lists the most recent stable release of each package. To do this:
+!!! warning
+    You must never directly edit this file. You will use `poetry update` commands to manage it.
 
-1. Create a new virtual environment.
-2. Install the latest version of all required packages `pip install -U -r base_requirements.txt`).
-3. Run all tests and check that the UI and API function as expected.
-4. Review each requirement's release notes for any breaking or otherwise noteworthy changes.
-5. Update the package versions in `requirements.txt` as appropriate.
+#### Run `poetry update`
+
+Every minor version release should refresh `poetry.lock`, so that it lists the most recent stable release of each package. To do this:
+
+1. Review each requirement's release notes for any breaking or otherwise noteworthy changes.
+2. Run `poetry update <package>` to update the package versions in `poetry.lock` as appropriate.
+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`.
+4. Run `poetry install` to install the refreshed versions of all required packages.
+5. Run all tests and check that the UI and API function as expected.
+
+!!! hint
+    You may use `poetry update --dry-run` to have Poetry automatically tell you what package updates are avaiable and the versions it would upgrade.
 
 ### Update Static Libraries
 
 Update the following static libraries to their most recent stable release:
 
-* Bootstrap 3
-* Material Design Icons
-* Select2
-* jQuery
-* jQuery UI
+* [Bootstrap 3](https://getbootstrap.com/docs/3.4)
+* [Material Design Icons](https://materialdesignicons.com/)
+* [Select2](https://github.com/select2/select2/releases)
+* [jQuery](https://jquery.com/download/)
+* [jQuery UI](https://jqueryui.com/)
 
 ### Link to the Release Notes Page
 
-Add the release notes (`/docs/release-notes/X.Y.md`) to the table of contents within `mkdocs.yml`, and point `index.md` to the new file.
+Add the release notes (`docs/release-notes/X.Y.md`) to the table of contents within `mkdocs.yml`, and point `index.md` to the new file.
 
-### Manually Perform a New Install
+### Verify and Revise the Install Documentation
 
-Install `mkdocs` in your local environment, then start the documentation server:
+Follow the [install instructions](../installation/nautobot.md) to perform a new production installation of Nautobot.
 
-```no-highlight
-$ pip install -r docs/requirements.txt
-$ mkdocs serve
-```
+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.
+
+!!! tip
+    Fire up `mkdocs serve` in your development environment to start the documentation server! This allows you to view the documentation locally and automatically rebuilds the documents as you make changes.
 
-Follow these instructions to perform a new installation of Nautobot. This process must _not_ be automated: The goal of this step is to catch any errors or omissions in the documentation, and ensure that it is kept up-to-date for each release. Make any necessary changes to the documentation before proceeding with the release.
+Commit any necessary changes to the documentation before proceeding with the release.
 
 ### Close the Release Milestone
 
@@ -62,9 +83,55 @@ Submit a pull request to merge the `feature` branch into the `develop` branch in
 
 Ensure that continuous integration testing on the `develop` branch is completing successfully.
 
-### Update Version and Changelog
+### Bump the Version
+
+Update the package version using `poetry version`. 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 should ideally 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:
+
+```no-highlight
+$ poetry version
+nautobot 1.0.0-beta.2
+```
+
+Bump pre-release versions using `prerelease`:
+
+```no-highlight
+$ poetry version prerelease
+Bumping version from 1.0.0-beta.2 to 1.0.0-beta.3
+```
+
+For major versions, use `major`:
+
+```no-highlight
+$ poetry version major
+Bumping version from 1.0.0-beta.2 to 1.0.0
+```
+
+For patch versions, use `minor`:
+
+```no-highlight
+$ poetry version minor
+Bumping version from 1.0.0 to 1.1.0
+```
+
+And lastly, for patch versions, you guessed it, use `patch`:
+
+```no-highlight
+$ poetry version patch
+Bumping version from 1.1.0 to 1.1.1
+```
+
+Please see the [official Poetry documentation on `version`](https://python-poetry.org/docs/cli/#version) for more information.
+
+### Update the Changelog
 
-Update the `VERSION` constant in `settings.py` to the new release version and annotate the current data in the release notes for the new version. Commit these changes to the `develop` branch.
+Update the release notes for the new version and commit these changes to the `develop` branch.
+
+!!! important
+    The changelog must adhere to the [Keep a Changelog](https://keepachangelog.com/) style guide.
 
 ### Submit a Pull Request
 
@@ -82,10 +149,29 @@ Draft a [new release](https://github.com/nautobot/nautobot/releases/new) with th
 
 Copy the description from the pull request to the release.
 
-### Update the Development Version
+### Publish to PyPI
+
+Now that there is a tagged release, the final step is to upload the package to the Python Package Index.
+
+First, you'll need to build the Python package distributions:
+
+```no-highlight
+$ poetry build
+```
+
+Next, publish to PyPI using the username `__token__` and the Nautobot PyPI API token as the password. The API token can be found in the Nautobot maintainers vault (if you're a maintainer, you'll have access to this vault):
+
+```
+$ poetry publish --username __token__ --password <api_token>
+```
+
+### Bump the Development Version
+
+Use `poetry version prepatch` to bump the version to the next release and commit it to the `develop` branch.
 
-On the `develop` branch, update `VERSION` in `settings.py` to point to the next release. For example, if you just released v2.9.9, set:
+For example, if you just released `v1.1.0`:
 
 ```
-VERSION = 'v2.9.10-dev'
+$ poetry version prepatch
+Bumping version from 1.1.0 to 1.1.1-alpha.0
 ```

nautobot/docs/development/user-preferences.md

@@ -6,6 +6,6 @@ The `users.User` model holds individual preferences for each user in the form of
 
 | Name | Description |
 | ---- | ----------- |
-| extras.configcontext.format | Preferred format when rendering config context data (JSON or YAML) |
-| pagination.per_page | The number of items to display per page of a paginated table |
-| tables.TABLE_NAME.columns | The ordered list of columns to display when viewing the table |
+| `extras.configcontext.format` | Preferred format when rendering config context data (JSON or YAML) |
+| `pagination.per_page` | The number of items to display per page of a paginated table |
+| `tables.TABLE_NAME.columns` | The ordered list of columns to display when viewing the table |