Add explanation of priority indicators to release notes#20402
Conversation
This proposal builds documents the release note priority indicators.
|
| App Name |  WordPress Alpha |
|
| Configuration | Release-Alpha | |
| Build Number | pr20402-6e30c77 | |
| Version | 22.0 | |
| Bundle ID | org.wordpress.alpha | |
| Commit | 6e30c77 | |
| App Center Build | WPiOS - One-Offs #5319 |
|
| App Name |  Jetpack Alpha |
|
| Configuration | Release-Alpha | |
| Build Number | pr20402-6e30c77 | |
| Version | 22.0 | |
| Bundle ID | com.jetpack.alpha | |
| Commit | 6e30c77 | |
| App Center Build | jetpack-installable-builds #4346 |
mokagio
left a comment
There was a problem hiding this comment.
I recall that scripts could break if the release notes don't follow a specific format, but I'm not sure which scripts or how. I'm requesting a review from someone familiar with the release process to help clarify this.
We have two release notes checks:
- If changes were made to the release notes, there must also be changes to the
AppStoreStringsfile - Warn if the
RELEASE-NOTES.txtfile has been changed in a PR targeting arelease/*branch
So this change complies with our checks' expectations 👍
| > [**] Medium Priority, e.g., Minor Enhancements Users Will Notice, etc. | ||
| > [*] Low Priority, e.g., Minor Enhancements Users May Miss, etc. |
There was a problem hiding this comment.
Reading "user may miss" made me think that we'd then want to let them know about it in the release notes, but that clashes with what "low priority" tells me 🤔
I wonder if that's just my perception being distorted by all the easter eggs videos I've been watching on YouTube, or if there's something we can do to align the language.
| > [***] High Priority, e.g., Major Enhancements, Widespread Crash Fixes, etc. | ||
| > [**] Medium Priority, e.g., Minor Enhancements Users Will Notice, etc. | ||
| > [*] Low Priority, e.g., Minor Enhancements Users May Miss, etc. |
There was a problem hiding this comment.
Unfortunately, we'll need to update the formatting here. Release toolkit expects header information such as this to start either with *** (like Woo does) or //.
| > [***] High Priority, e.g., Major Enhancements, Widespread Crash Fixes, etc. | |
| > [**] Medium Priority, e.g., Minor Enhancements Users Will Notice, etc. | |
| > [*] Low Priority, e.g., Minor Enhancements Users May Miss, etc. | |
| // [***] High Priority, e.g., Major Enhancements, Widespread Crash Fixes, etc. | |
| // [**] Medium Priority, e.g., Minor Enhancements Users Will Notice, etc. | |
| // [*] Low Priority, e.g., Minor Enhancements Users May Miss, etc. |
I verified this using a test branch. See effect on formatting using > where the new version ends up on top of this info, and effect with // which behaves as desired.
There was a problem hiding this comment.
While I'm suggesting changes, what do you think of adding an explanation for that information?
Taking inspiration from the wording Woo uses:
| > [***] High Priority, e.g., Major Enhancements, Widespread Crash Fixes, etc. | |
| > [**] Medium Priority, e.g., Minor Enhancements Users Will Notice, etc. | |
| > [*] Low Priority, e.g., Minor Enhancements Users May Miss, etc. | |
| // Please use the following: [<priority indicator>] <description> [<PR URL>]. | |
| // | |
| // When assigning priorities follow this convention: | |
| // | |
| // - [***] High Priority, e.g., Major Enhancements, Widespread Crash Fixes, etc. | |
| // - [**] Medium Priority, e.g., Minor Enhancements Users Will Notice, etc. | |
| // - [*] Low Priority, e.g., Minor Enhancements Users May Miss, etc. |
|
@guarani I'm going to close this given there hasn't been any activity in a long time. Feel free to reopen if needed, but it looks like we've all absorbed the meaning of those indicators (or have been using them inconsistently but with no visible damage) |
This proposal documents the release note priority indicators.
To test:
Ensure that no bots break with the addition of this change. 🤖
I recall that scripts could break if the release notes don't follow a specific format, but I'm not sure which scripts or how. I'm requesting a review from someone familiar with the release process to help clarify this.
Regression Notes
Scripts relating to this repo could break due to this change.
I'm requesting a review from release wranglers to help verify if this could break a script.
Not applicable since this is a documentation change.
PR submission checklist:
RELEASE-NOTES.txtif necessary.