Add Documentation / Maintenance subgroups to release notes

Reorganise the 4.2 release notes and changelog to include new sections for documentation and maintenance. This helps to highlight the most relevant changes from the perspective of a developer wanting to know what they can expect from an upgrade, while still recognising less visible contributions. Also update the "committing code" docs to explain the new classification scheme.

CHANGELOG.txt

@@ -4,30 +4,11 @@ Changelog
 4.2 (xx.xx.xxxx) - IN DEVELOPMENT
 ~~~~~~~~~~~~~~~~
 
- * Add custom permissions section to permissions documentation page (Dan Hayden)
- * Remove unsquashed `testapp` migrations (Matt Westcott)
  * Switch to using Willow instead of Pillow for images (Darrel O'Pry)
- * Add documentation for how to get started with contributing translations for the Wagtail admin (Ogunbanjo Oluwadamilare)
- * Upgrade to Node 18 for frontend build tooling (LB (Ben) Johnston)
- * Officially recommend `fnm` over `nvm` in development documentation (LB (Ben) Johnston)
  * Test assertion util `WagtailPageTestCase.assertCanCreate` now supports the kwarg `publish=True` to check publish redirection (Harry Percival, Akua Dokua Asiedu)
- * Mention the importance of passing `request` and `current_site` to `get_url` on the [performance](performance) documentation page (Jake Howard)
- * Run Python tests with coverage and upload coverage data to codecov (Sage Abdullah)
- * Clean up duplicate JavaScript for the `escapeHtml` function (Jordan Rob)
- * Add documentation for `register_user_listing_buttons` hook (LB (Ben Johnston))
- * Clean up Prettier & Eslint usage for search promotions formset JS file (LB (Ben Johnston))
- * Ensure that translation file generation ignores JavaScript unit tests and clean up unit tests for Django gettext utils (LB (Ben Johnston))
- * Migrated `initButtonSelects` from core.js to own TypesScript file and add unit tests (Loveth Omokaro)
- * Migrated `initSkipLink` util to TypeScript and add JSDoc & unit tests (Juliet Adeboye)
- * Clean up some unused utility classes and migrate `unlist` to Tailwind utility class `w-list-none` (Loveth Omokaro)
  * Ensure that the `rebuild_references_index` command can run without console output if called with `--verbosity 0` (Omerzahid Ali, Aman Pandey)
- * Add development (contributing to Wagtail) documentation notes for development on Windows (Akua Dokua Asiedu)
- * Clean up linting on legacy code and add shared util `hasOwn` in TypeScript (Loveth Omokaro)
- * Remove unnecessary box-sizing: border-box declarations in SCSS (Albina Starykova)
  * Add full support for secondary buttons with icons in the Wagtail design system - `button bicolor button--icon button-secondary` including the `button-small` variant (Seremba Patrick)
- * Migrated `initTooltips` to TypeScript add JSDoc and unit tests (Fatuma Abdullahi)
  * Add `purge_embeds` management command to delete all the cached embed objects in the database (Aman Pandey)
- * Migrated `initTagField` from core.js to own TypesScript file and add unit tests (Chisom Okeoma)
  * Fix: Make sure workflow timeline icons are visible in high-contrast mode (Loveth Omokaro)
  * Fix: Ensure authentication forms (login, password reset) have a visible border in Windows high-contrast mode (Loveth Omokaro)
  * Fix: Ensure visual consistency between buttons and links as buttons in Windows high-contrast mode (Albina Starykova)
@@ -43,6 +24,25 @@ Changelog
  * Fix: Ensure there is a visual difference of 'active/current link' vs normal links in Windows high-contrast mode (Mohammad Areeb)
  * Fix: Avoid issues where trailing whitespace could be accidentally removed in translations for new page & snippet headers (Florian Vogt)
  * Fix: Make sure minimap error indicators follow the minimap scrolling (Thibaud Colas)
+ * Docs: Add custom permissions section to permissions documentation page (Dan Hayden)
+ * Docs: Add documentation for how to get started with contributing translations for the Wagtail admin (Ogunbanjo Oluwadamilare)
+ * Docs: Officially recommend `fnm` over `nvm` in development documentation (LB (Ben) Johnston)
+ * Docs: Mention the importance of passing `request` and `current_site` to `get_url` on the performance documentation page (Jake Howard)
+ * Docs: Add documentation for `register_user_listing_buttons` hook (LB (Ben Johnston))
+ * Docs: Add development (contributing to Wagtail) documentation notes for development on Windows (Akua Dokua Asiedu)
+ * Maintenance: Remove unsquashed `testapp` migrations (Matt Westcott)
+ * Maintenance: Upgrade to Node 18 for frontend build tooling (LB (Ben) Johnston)
+ * Maintenance: Run Python tests with coverage and upload coverage data to codecov (Sage Abdullah)
+ * Maintenance: Clean up duplicate JavaScript for the `escapeHtml` function (Jordan Rob)
+ * Maintenance: Clean up Prettier & Eslint usage for search promotions formset JS file (LB (Ben Johnston))
+ * Maintenance: Ensure that translation file generation ignores JavaScript unit tests and clean up unit tests for Django gettext utils (LB (Ben Johnston))
+ * Maintenance: Migrated `initButtonSelects` from core.js to own TypesScript file and add unit tests (Loveth Omokaro)
+ * Maintenance: Migrated `initSkipLink` util to TypeScript and add JSDoc & unit tests (Juliet Adeboye)
+ * Maintenance: Clean up some unused utility classes and migrate `unlist` to Tailwind utility class `w-list-none` (Loveth Omokaro)
+ * Maintenance: Clean up linting on legacy code and add shared util `hasOwn` in TypeScript (Loveth Omokaro)
+ * Maintenance: Remove unnecessary box-sizing: border-box declarations in SCSS (Albina Starykova)
+ * Maintenance: Migrated `initTooltips` to TypeScript add JSDoc and unit tests (Fatuma Abdullahi)
+ * Maintenance: Migrated `initTagField` from core.js to own TypeScript file and add unit tests (Chisom Okeoma)
 
 
 4.1.1 (11.11.2022)

docs/contributing/committing.md

@@ -70,8 +70,14 @@ and the release notes for the current version.
 
 The `CHANGELOG.txt` contains a short summary of each new feature, refactoring, or bug fix in each release.
 Each summary should be a single line.
-Bug fixes should be grouped together at the end of the list for each release,
-and be prefixed with "Fix:".
+To easily identify the most relevant changes to users, items are grouped together in the following order:
+
+* Major features (no prefix) - things that will inspire users to upgrade to a new release
+* Minor enhancements (no prefix) - other improvements to the developer or end user experience
+* Bug fixes (prefixed with "Fix:") - things that address broken behaviour from previous releases
+* Documentation (prefixed with "Docs:") - changes to documentation that do not accompany a specific code change; reorganisations, tutorials, recipes and so on
+* Maintenance (prefixed with "Maintenance:") - cleanup, refactoring and other changes to code or tooling that are not intended to have a visible effect to developers or end users
+
 The name of the contributor should be added at the end of the summary, in brackets.
 For example:
 
@@ -79,11 +85,9 @@ For example:
 * Fix: Tags added on the multiple image uploader are now saved correctly (Alex Smith)
 ```
 
-The release notes for each version contain a more detailed description of each change.
-Backwards compatibility notes should also be included.
-Large new features or changes should get their own section,
-while smaller changes and bug fixes should be grouped together in their own section.
-See previous release notes for examples.
+The release notes for each version contain a more detailed description for each major feature, under its own heading.
+Minor enhancements ("Other features"), bug fixes, documentation and maintenance are listed as bullet points under the appropriate heading - these can be copied from the changelog, with the prefix ("Fix:", "Docs:" or "Maintenance:") removed.
+Backwards compatibility notes should also be included. See previous release notes for examples.
 The release notes for each version are found in `docs/releases/x.x.x.md`.
 
 If the contributor is a new person, and this is their first contribution to Wagtail,

docs/releases/4.2.md

@@ -14,29 +14,11 @@ depth: 1
 
 ### Other features
 
- * Add custom permissions section to permissions documentation page (Dan Hayden)
- * Wagtail's documentation (v2.9 to v4.1) has been updated on [Dash user contributions](https://github.com/Kapeli/Dash-User-Contributions) for [Dash](https://kapeli.com/dash) or [Zeal](https://zealdocs.org/) offline docs applications (Damilola Oladele, Mary Ayobami, Elizabeth Bassey)
  * Switch to using [Willow](https://github.com/wagtail/Willow/) instead of Pillow for images (Darrel O'Pry)
- * Add documentation for how to get started with [contributing translations](contributing_translations) for the Wagtail admin (Ogunbanjo Oluwadamilare)
  * Test assertion [`WagtailPageTestCase.assertCanCreate`](testing_reference) now supports the kwarg `publish=True` to check publish redirection (Harry Percival, Akua Dokua Asiedu)
- * Upgrade to Node 18 for frontend build tooling (LB (Ben) Johnston)
- * Officially recommend `fnm` over `nvm` in development documentation (LB (Ben) Johnston)
- * Mention the importance of passing `request` and `current_site` to `get_url` on the [performance](performance) documentation page (Jake Howard)
- * Run Python tests with coverage and upload coverage data to codecov (Sage Abdullah)
- * Clean up duplicate JavaScript for the `escapeHtml` function (Jordan Rob)
- * Add documentation for [`register_user_listing_buttons`](register_user_listing_buttons) hook (LB (Ben Johnston))
- * Ensure that translation file generation ignores JavaScript unit tests and clean up unit tests for Django gettext utils (LB (Ben Johnston))
- * Migrated `initButtonSelects` from core.js to own TypesScript file and add unit tests (Loveth Omokaro)
- * Migrated `initSkipLink` util to TypeScript and add JSDoc & unit tests (Juliet Adeboye)
- * Clean up some unused utility classes and migrate `unlist` to Tailwind utility class `w-list-none` (Loveth Omokaro)
  * Ensure that the `rebuild_references_index` command can run without console output if called with `--verbosity 0` (Omerzahid Ali, Aman Pandey)
- * Add development (contributing to Wagtail) documentation notes for [development on Windows](development_on_windows) (Akua Dokua Asiedu)
- * Clean up linting on legacy code and add shared util `hasOwn` in TypeScript (Loveth Omokaro)
- * Remove unnecessary box-sizing: border-box declarations in SCSS (Albina Starykova)
  * Add full support for secondary buttons with icons in the Wagtail design system - `button bicolor button--icon button-secondary` including the `button-small` variant (Seremba Patrick)
- * Migrated `initTooltips` to TypeScript add JSDoc and unit tests (Fatuma Abdullahi)
  * Add [`purge_embeds`](purge_embeds) management command to delete all the cached embed objects in the database (Aman Pandey)
- * Migrated `initTagField` from core.js to own TypesScript file and add unit tests (Chisom Okeoma)
 
 ### Bug fixes
 
@@ -55,6 +37,30 @@ depth: 1
  * Avoid issues where trailing whitespace could be accidentally removed in translations for new page & snippet headers (Florian Vogt)
  * Make sure minimap error indicators follow the minimap scrolling (Thibaud Colas)
 
+### Documentation
+
+ * Add custom permissions section to permissions documentation page (Dan Hayden)
+ * Wagtail's documentation (v2.9 to v4.0) has been updated on [Dash user contributions](https://github.com/Kapeli/Dash-User-Contributions) for [Dash](https://kapeli.com/dash) or [Zeal](https://zealdocs.org/) offline docs applications (Damilola Oladele, Mary Ayobami, Elizabeth Bassey)
+ * Add documentation for how to get started with [contributing translations](contributing_translations) for the Wagtail admin (Ogunbanjo Oluwadamilare)
+ * Officially recommend `fnm` over `nvm` in development documentation (LB (Ben) Johnston)
+ * Mention the importance of passing `request` and `current_site` to `get_url` on the [performance](performance) documentation page (Jake Howard)
+ * Add documentation for [`register_user_listing_buttons`](register_user_listing_buttons) hook (LB (Ben Johnston))
+ * Add development (contributing to Wagtail) documentation notes for [development on Windows](development_on_windows) (Akua Dokua Asiedu)
+
+### Maintenance
+
+ * Upgrade to Node 18 for frontend build tooling (LB (Ben) Johnston)
+ * Run Python tests with coverage and upload coverage data to codecov (Sage Abdullah)
+ * Clean up duplicate JavaScript for the `escapeHtml` function (Jordan Rob)
+ * Ensure that translation file generation ignores JavaScript unit tests and clean up unit tests for Django gettext utils (LB (Ben Johnston))
+ * Migrated `initButtonSelects` from core.js to own TypesScript file and add unit tests (Loveth Omokaro)
+ * Migrated `initSkipLink` util to TypeScript and add JSDoc & unit tests (Juliet Adeboye)
+ * Clean up some unused utility classes and migrate `unlist` to Tailwind utility class `w-list-none` (Loveth Omokaro)
+ * Clean up linting on legacy code and add shared util `hasOwn` in TypeScript (Loveth Omokaro)
+ * Remove unnecessary box-sizing: border-box declarations in SCSS (Albina Starykova)
+ * Migrated `initTooltips` to TypeScript add JSDoc and unit tests (Fatuma Abdullahi)
+ * Migrated `initTagField` from core.js to own TypeScript file and add unit tests (Chisom Okeoma)
+
 ## Upgrade considerations
 
 ### Wagtail-specific image field (`WagtailImageField`)