Add draft release notes for Review Board 7.0
Review Request #13919 — Created June 3, 2024 and submitted
This change adds the draft release notes for Review Board 7.0.
This does not include any screenshots for things right now, just
text content.
Built HTML and checked the output.
Summary | ID |
---|---|
5015f7ff64c53798e5b8a6af180895a2ae475101 |
Description | From | Last Updated |
---|---|---|
A couple things stood out to me generally in this change: We're quoting a lot of UI concepts. We haven't … |
chipx86 | |
As a reminder, we need to document any removed code that was deprecated, and any new deprecations, for extension authors. |
chipx86 | |
Should be _clean-orphaned-data. |
chipx86 | |
Let's use a literal here. |
chipx86 | |
We should list the dropped version. |
chipx86 | |
The "which" kind of reads oddly to me, but I also think we can be a bit more clear in … |
chipx86 | |
Let's link to the RBTools page. |
chipx86 | |
Let's capitalize this as "Dark Mode" wherever we reference it. This is the name of the feature, not just a … |
chipx86 | |
Same with "Light Mode". |
chipx86 | |
Going with more of a marketing-focused view, how about: Diffs can now be reviewed on mobile devices. |
chipx86 | |
We should link both. |
chipx86 | |
Pytest_-based. We should also link Nose, for reference/context. |
chipx86 | |
This is a bit verbose for a summary (3 lines is a lot). These should all be clearly skimmable. How … |
chipx86 | |
We should link each of these tools. Even people who may be familiar with Babel may not know what Rollup … |
chipx86 | |
"Web API" also gets its own top-level section, after "New Features". I'll work on a standard template after this release, … |
chipx86 | |
We should link to HSTS, and maybe the rest, to help admins learn about this. |
chipx86 | |
There's a lot of good information in here, and we should add a task to add this to the docs. … |
chipx86 | |
settings_local.py. |
chipx86 | |
We should be able to reference this module directly up above, since Django's in the intersphinx. We can still give … |
chipx86 | |
Can we describe this briefly? |
chipx86 | |
Let's use :term: here around "Local Site" so that users can learn what that means. It'll link to the glossary. |
chipx86 | |
I think we need to clarify this a bit. It can read both as "Fixed removing data" as in we … |
chipx86 | |
Too many blank lines. |
chipx86 | |
Feels like a word is missing here. "Fixed removing <what> when deleting ..." ? This would be subject to the … |
chipx86 | |
Or on the CDN. Maybe "file storage"? |
chipx86 | |
We should use a literal here. I feel like the library name isn't the highlight, though. We should just say … |
chipx86 | |
We should use :guilabel: instead of quotes. |
chipx86 | |
This could just be me being pretty sleepy, but I had to read this a couple times. I was reading … |
chipx86 | |
"Previously" would be a good place to begin a new paragraph, since we just finished explaining the background leading up … |
chipx86 | |
Do we have docs we can link to instead of using quotes? |
chipx86 | |
:guilabel: would be better for these. |
chipx86 | |
We're using "diff viewer" here but "Diff Viewer" below. We should make sure we're consistent everywhere. |
chipx86 | |
Let's link to the release notes for 6 here. |
chipx86 | |
This isn't reading right to me. The "back to the diff" part seems out of place. Maybe: Fixed links from … |
chipx86 | |
Can we clarify this? I'm not sure what this is saying. |
chipx86 | |
Can we say how it displayed incorrectly, so it's more clear what the wrong behavior was? |
chipx86 | |
We generally capitalize this as Issue Summary Table (and should here, since we're doing so with most other references). We … |
chipx86 | |
Maybe specifically say "web browser caching conflicts." |
chipx86 | |
Maybe "Review UIs now display an error ..." |
chipx86 | |
"Extensions" gets its own top-level section after "New Features". |
chipx86 | |
We should link HideActionHook. |
chipx86 | |
Just to help clarify this, maybe something like: Fixed invisible links to file attachments without captions set in :guilabel:`Admin UI … |
chipx86 | |
We should explain what this means. It's too vague. |
chipx86 | |
Good opportunity for :guilabel:. Also, what kind of visual glitches? |
chipx86 | |
:guilabel: would be good here, too. And other widgets below. |
chipx86 | |
We have a couple Docker things spread out. This should all be in a Docker section. |
chipx86 | |
This should go in New Features somewhere, rather than getting its own top-level section. |
chipx86 | |
This section traditionally goes before Bug Fixes. |
chipx86 | |
Performance Improvements goes before Usability Improvements. |
chipx86 | |
Let's use :term: for Local Sites. |
chipx86 | |
I'd say this belongs more in Bug Fixes -> Integrations. |
chipx86 | |
A lot of this section should be split into subsections, to ease scanning. I'd add: Authentication (redirect loops) Local Sites … |
chipx86 | |
For the reference, we can use: :doc:`Review Board 6 <6.0>` (Double-check that the reference works, but that should be it.) |
chipx86 | |
Anything referencing something on a class needs to have that Class.thing as a title. |
chipx86 | |
General is usually first. |
chipx86 | |
Debating on this, but maybe this should go in Reviews? We've also historically had a Review Requests section, but it … |
chipx86 |
-
-
A couple things stood out to me generally in this change:
- We're quoting a lot of UI concepts. We haven't historically done this, instead just letting Proper Nouns speak for themselves. If we do want to label anything, we should use
:guilabel:
- We've never capitalized "Review requests" as "Review Requests". I'm not opposed, but it's a new thing, and we should decide if that's how we want to address it 100% of the time going forward.
- We're quoting a lot of UI concepts. We haven't historically done this, instead just letting Proper Nouns speak for themselves. If we do want to label anything, we should use
-
As a reminder, we need to document any removed code that was deprecated, and any new deprecations, for extension authors.
-
-
-
-
The "which" kind of reads oddly to me, but I also think we can be a bit more clear in general on this. Maybe:
Review Board now supports displaying, reviewing, and diffing certain types of binary files included as part of your changes posted for review. At the moment, this is limited to image files, but support for additional file types are in the works.
-
-
Let's capitalize this as "Dark Mode" wherever we reference it. This is the name of the feature, not just a dark mode.
-
-
Going with more of a marketing-focused view, how about:
Diffs can now be reviewed on mobile devices.
-
-
-
This is a bit verbose for a summary (3 lines is a lot). These should all be clearly skimmable.
How about something like:
Extensions can now be built using modern TypeScript, JavaScript, and CSS tools.
Then we can add a version of this paragraph as the first in the description.
-
We should link each of these tools. Even people who may be familiar with Babel may not know what Rollup or TSC is (we could say "TSC (the TypeScript compiler)").
Also,
.npm-workspaces
is our creation, so we need to at least mention that this is a directory at the root of their source tree. -
"Web API" also gets its own top-level section, after "New Features".
I'll work on a standard template after this release, to help with future release notes.
-
-
There's a lot of good information in here, and we should add a task to add this to the docs.
For this paragraph, I feel like we should split this into the explanation of the setting and then into the conditions around it ("The particular settings will depend ... See the Django documentation ...")
We should also link to the Django documentation when we say it.
-
-
We should be able to reference this module directly up above, since Django's in the intersphinx. We can still give it this title.
-
-
Let's use
:term:
here around "Local Site" so that users can learn what that means. It'll link to the glossary. -
I think we need to clarify this a bit. It can read both as "Fixed removing data" as in we fixed the operation of removing data, or as in we fixed it from removing data (which sounds scary).
-
-
Feels like a word is missing here. "Fixed removing <what> when deleting ..." ?
This would be subject to the same clarification as above.
-
-
We should use a literal here.
I feel like the library name isn't the highlight, though. We should just say that we fixed LDAP support.
-
-
This could just be me being pretty sleepy, but I had to read this a couple times. I was reading it as "... which were creating with RBTools using ((Git or Mercurial) track commit history)".
Maybe:
When posting a change using RBTools with either Git or Mercurial, the review request will keep track of all the commits included in your change. This allows ...
-
"Previously" would be a good place to begin a new paragraph, since we just finished explaining the background leading up to this change.
Also,
:guilabel:
maybe for "Update Diff". -
-
-
We're using "diff viewer" here but "Diff Viewer" below. We should make sure we're consistent everywhere.
-
-
This isn't reading right to me. The "back to the diff" part seems out of place. Maybe:
Fixed links from comments back to the diff when viewing commit ranges
Or something?
-
-
-
We generally capitalize this as Issue Summary Table (and should here, since we're doing so with most other references).
We could link as well.
-
-
-
-
-
Just to help clarify this, maybe something like:
Fixed invisible links to file attachments without captions set in :guilabel:`Admin UI -> Database -> File Attachments`
-
-
-
-
-
-
-
-
- Change Summary:
-
Updated for everything except deprecations
- Commits:
-
Summary ID 9f4b3930e895dfef8a949609aaa02a12ca346d3e 1d3c9541c5810dc662ce0f749840ffe457f36da4
Checks run (2 succeeded)
- Change Summary:
-
Update to include information about deprecations, fixes from Djblets 5.0, and features/fixes from rbintegrations 4.0
- Commits:
-
Summary ID 1d3c9541c5810dc662ce0f749840ffe457f36da4 a994577423d727b92aa8b64f24b452113fe1cb52
Checks run (2 succeeded)
-
Basically done, but there's a bit of organizational stuff left to help with reading through affected fixes.
-
-
A lot of this section should be split into subsections, to ease scanning. I'd add:
- Authentication (redirect loops)
- Local Sites
- Dashboard (includes other datagrids)
- Diff Viewer
- My Account
And some of these (like action-related things) can be put into Reviews.
It's okay if there's only one per section. The important part is making it easy to scan for the category of the bugs that were fixed. General should be as small as possible.
-
For the reference, we can use:
:doc:`Review Board 6 <6.0>`
(Double-check that the reference works, but that should be it.)
-
- Commits:
-
Summary ID a994577423d727b92aa8b64f24b452113fe1cb52 5265d05dfceb03e339f040e901d7b09af6d58f6d