Misc cleanup of the release checklist

Author: jeremystretch

docs/development/release-checklist.md

@@ -8,6 +8,8 @@ This documentation describes the process of packaging and publishing a new NetBo
 
 While major releases generally introduce some very substantial change to the application, they are typically treated the same as minor version increments for the purpose of release packaging.
 
+For patch releases (e.g. upgrading from v4.2.2 to v4.2.3), begin at the [patch releases](#patch-releases) heading below. For minor or major releases, complete the entire checklist.
+
 ## Minor Version Releases
 
 ### Address Constrained Dependencies
@@ -85,7 +87,20 @@ In cases where upgrading a dependency to its most recent release is breaking, it
 
 ### Update UI Dependencies
 
-Check whether any UI dependencies (JavaScript packages, fonts, etc.) need to be updated by running `yarn outdated` from within the `project-static/` directory. [Upgrade these dependencies](./web-ui.md#updating-dependencies) as necessary, then run `yarn bundle` to generate the necessary files for distribution.
+Check whether any UI dependencies (JavaScript packages, fonts, etc.) need to be updated by running `yarn outdated` from within the `project-static/` directory. [Upgrade these dependencies](./web-ui.md#updating-dependencies) as necessary, then run `yarn bundle` to generate the necessary files for distribution:
+
+```
+$ yarn bundle
+yarn run v1.22.19
+$ node bundle.js
+✅ Bundled source file 'styles/external.scss' to 'netbox-external.css'
+✅ Bundled source file 'styles/netbox.scss' to 'netbox.css'
+✅ Bundled source file 'styles/svg/rack_elevation.scss' to 'rack_elevation.css'
+✅ Bundled source file 'styles/svg/cable_trace.scss' to 'cable_trace.css'
+✅ Bundled source file 'index.ts' to 'netbox.js'
+✅ Copied graphiql files
+Done in 1.00s.
+```
 
 ### Rebuild the Device Type Definition Schema
 
@@ -116,16 +131,22 @@ Then, compile these portable (`.po`) files for use in the application:
 
 ### Update Version and Changelog
 
-* Update the version and published date in `release.yaml` with the current version & date. Add a designation (e.g.g `beta1`) if applicable.
+* Update the version number and date in `netbox/release.yaml`. Add or remove the designation (e.g. `beta1`) if applicable.
 * Update the example version numbers in the feature request and bug report templates under `.github/ISSUE_TEMPLATES/`.
-* Replace the "FUTURE" placeholder in the release notes with the current date.
+* Add a section for this release at the top of the changelog page for the minor version (e.g. `docs/release-notes/version-4.2.md`) listing all relevant changes made in this release.
+
+!!! tip
+    Put yourself in the shoes of the user when recording change notes. Focus on the effect that each change has for the end user, rather than the specific bits of code that were modified in a PR. Ensure that each message conveys meaning absent context of the initial feature request or bug report. Remember to include key words or phrases (such as exception names) that can be easily searched.
 
 ### Submit a Pull Request
 
 Commit the above changes and submit a pull request titled **"Release vX.Y.Z"** to merge the current release branch (e.g. `release-vX.Y.Z`) into `main`. Copy the documented release notes into the pull request's body.
 
 Once CI has completed and a colleague has reviewed the PR, merge it. This effects a new release in the `main` branch.
 
+!!! warning
+    To ensure a streamlined review process, the pull request for a release **must** be limited to the changes outlined in this document. A release PR must never include functional changes to the application: Any unrelated "cleanup" needs to be captured in a separate PR prior to the release being shipped.
+
 ### Create a New Release
 
 Create a [new release](https://github.com/netbox-community/netbox/releases/new) on GitHub with the following parameters.

docs/development/translations.md

@@ -30,7 +30,7 @@ To download translated strings automatically, you'll need to:
 1. Install the [Transifex CLI client](https://github.com/transifex/cli)
 2. Generate a [Transifex API token](https://app.transifex.com/user/settings/api/)
 
-Once you have the client set up, run the following command:
+Once you have the client set up, run the following command from the project root (e.g. `/opt/netbox/`):
 
 ```no-highlight
 TX_TOKEN=$TOKEN tx pull
@@ -46,6 +46,9 @@ Once retrieved, the updated strings need to be compiled into new `.mo` files so
 
 Once any new `.mo` files have been generated, they need to be committed and pushed back up to GitHub. (Again, this is typically done as part of publishing a new NetBox release.)
 
+!!! tip
+    Run `git status` to check that both `*.mo` & `*.po` files have been updated as expected.
+
 ## Proposing New Languages
 
 If you'd like to add support for a new language to NetBox, the first step is to [submit a GitHub issue](https://github.com/netbox-community/netbox/issues/new?assignees=&labels=type%3A+translation&projects=&template=translation.yaml) to capture the proposal. While we'd like to add as many languages as possible, we do need to limit the rate at which new languages are added. New languages will be selected according to community interest and the number of volunteers who sign up as translators.