Add draft release notes for Review Board 7.0

Review Request #13919 — Created June 3, 2024 and submitted

Information

Review Board
release-7.x

Reviewers

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
Add draft release notes for Review Board 7.0
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. Testing Done: Built HTML and checked the output.
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 …

chipx86chipx86

As a reminder, we need to document any removed code that was deprecated, and any new deprecations, for extension authors.

chipx86chipx86

Should be _clean-orphaned-data.

chipx86chipx86

Let's use a literal here.

chipx86chipx86

We should list the dropped version.

chipx86chipx86

The "which" kind of reads oddly to me, but I also think we can be a bit more clear in …

chipx86chipx86

Let's link to the RBTools page.

chipx86chipx86

Let's capitalize this as "Dark Mode" wherever we reference it. This is the name of the feature, not just a …

chipx86chipx86

Same with "Light Mode".

chipx86chipx86

Going with more of a marketing-focused view, how about: Diffs can now be reviewed on mobile devices.

chipx86chipx86

We should link both.

chipx86chipx86

Pytest_-based. We should also link Nose, for reference/context.

chipx86chipx86

This is a bit verbose for a summary (3 lines is a lot). These should all be clearly skimmable. How …

chipx86chipx86

We should link each of these tools. Even people who may be familiar with Babel may not know what Rollup …

chipx86chipx86

"Web API" also gets its own top-level section, after "New Features". I'll work on a standard template after this release, …

chipx86chipx86

We should link to HSTS, and maybe the rest, to help admins learn about this.

chipx86chipx86

There's a lot of good information in here, and we should add a task to add this to the docs. …

chipx86chipx86

settings_local.py.

chipx86chipx86

We should be able to reference this module directly up above, since Django's in the intersphinx. We can still give …

chipx86chipx86

Can we describe this briefly?

chipx86chipx86

Let's use :term: here around "Local Site" so that users can learn what that means. It'll link to the glossary.

chipx86chipx86

I think we need to clarify this a bit. It can read both as "Fixed removing data" as in we …

chipx86chipx86

Too many blank lines.

chipx86chipx86

Feels like a word is missing here. "Fixed removing <what> when deleting ..." ? This would be subject to the …

chipx86chipx86

Or on the CDN. Maybe "file storage"?

chipx86chipx86

We should use a literal here. I feel like the library name isn't the highlight, though. We should just say …

chipx86chipx86

We should use :guilabel: instead of quotes.

chipx86chipx86

This could just be me being pretty sleepy, but I had to read this a couple times. I was reading …

chipx86chipx86

"Previously" would be a good place to begin a new paragraph, since we just finished explaining the background leading up …

chipx86chipx86

Do we have docs we can link to instead of using quotes?

chipx86chipx86

:guilabel: would be better for these.

chipx86chipx86

We're using "diff viewer" here but "Diff Viewer" below. We should make sure we're consistent everywhere.

chipx86chipx86

Let's link to the release notes for 6 here.

chipx86chipx86

This isn't reading right to me. The "back to the diff" part seems out of place. Maybe: Fixed links from …

chipx86chipx86

Can we clarify this? I'm not sure what this is saying.

chipx86chipx86

Can we say how it displayed incorrectly, so it's more clear what the wrong behavior was?

chipx86chipx86

We generally capitalize this as Issue Summary Table (and should here, since we're doing so with most other references). We …

chipx86chipx86

Maybe specifically say "web browser caching conflicts."

chipx86chipx86

Maybe "Review UIs now display an error ..."

chipx86chipx86

"Extensions" gets its own top-level section after "New Features".

chipx86chipx86

We should link HideActionHook.

chipx86chipx86

Just to help clarify this, maybe something like: Fixed invisible links to file attachments without captions set in :guilabel:`Admin UI …

chipx86chipx86

We should explain what this means. It's too vague.

chipx86chipx86

Good opportunity for :guilabel:. Also, what kind of visual glitches?

chipx86chipx86

:guilabel: would be good here, too. And other widgets below.

chipx86chipx86

We have a couple Docker things spread out. This should all be in a Docker section.

chipx86chipx86

This should go in New Features somewhere, rather than getting its own top-level section.

chipx86chipx86

This section traditionally goes before Bug Fixes.

chipx86chipx86

Performance Improvements goes before Usability Improvements.

chipx86chipx86

Let's use :term: for Local Sites.

chipx86chipx86

I'd say this belongs more in Bug Fixes -> Integrations.

chipx86chipx86

A lot of this section should be split into subsections, to ease scanning. I'd add: Authentication (redirect loops) Local Sites …

chipx86chipx86

For the reference, we can use: :doc:`Review Board 6 <6.0>` (Double-check that the reference works, but that should be it.)

chipx86chipx86

Anything referencing something on a class needs to have that Class.thing as a title.

chipx86chipx86

General is usually first.

chipx86chipx86

Debating on this, but maybe this should go in Reviews? We've also historically had a Review Requests section, but it …

chipx86chipx86
chipx86
  1. I haven't gone through the tree to see if anything's missing. This looks pretty thorough, though.

    There's some consistency issues between this and previous release notes that I want to hammer out, in terms of section ordering, summary / description breakdowns, and the ways we name things.

    For summaries, we want to aim to be skimmable. This is good for readers and for Google SEO. Simple summary that's explanatory enough, detailed description broken into smaller chunks of paragraphs and/or bullet lists. For now, look at the 6.0 docs. We also need to ensure that a person can get enough information out of any given entry to learn about the fix, other than just the "vague thing about this feature is fixed." That includes us when trying to track down when we actually addressed some fix we need to backport to somebody.

    For sections, I mention this in another comment, but I'll put a task on my plate to get standard templates for future releases going so it's easier to just start plugging things in.

  2. Show all issues

    A couple things stood out to me generally in this change:

    1. 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:
    2. 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.
  3. Show all issues

    As a reminder, we need to document any removed code that was deprecated, and any new deprecations, for extension authors.

  4. Show all issues

    Should be _clean-orphaned-data.

  5. docs/releasenotes/7.0.rst (Diff revision 1)
     
     
    Show all issues

    Let's use a literal here.

  6. docs/releasenotes/7.0.rst (Diff revision 1)
     
     
    Show all issues

    We should list the dropped version.

  7. docs/releasenotes/7.0.rst (Diff revision 1)
     
     
    Show all issues

    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.
    
  8. docs/releasenotes/7.0.rst (Diff revision 1)
     
     
    Show all issues

    Let's link to the RBTools page.

  9. docs/releasenotes/7.0.rst (Diff revision 1)
     
     
    Show all issues

    Let's capitalize this as "Dark Mode" wherever we reference it. This is the name of the feature, not just a dark mode.

  10. docs/releasenotes/7.0.rst (Diff revision 1)
     
     
    Show all issues

    Same with "Light Mode".

  11. docs/releasenotes/7.0.rst (Diff revision 1)
     
     
    Show all issues

    Going with more of a marketing-focused view, how about:

    Diffs can now be reviewed on mobile devices.
    
  12. docs/releasenotes/7.0.rst (Diff revision 1)
     
     
    Show all issues

    We should link both.

  13. docs/releasenotes/7.0.rst (Diff revision 1)
     
     
    Show all issues

    Pytest_-based.

    We should also link Nose, for reference/context.

  14. docs/releasenotes/7.0.rst (Diff revision 1)
     
     
     
     
    Show all issues

    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.

  15. docs/releasenotes/7.0.rst (Diff revision 1)
     
     
     
    Show all issues

    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.

  16. docs/releasenotes/7.0.rst (Diff revision 1)
     
     
     
    Show all issues

    "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.

  17. docs/releasenotes/7.0.rst (Diff revision 1)
     
     
    Show all issues

    We should link to HSTS, and maybe the rest, to help admins learn about this.

  18. docs/releasenotes/7.0.rst (Diff revision 1)
     
     
     
     
     
     
    Show all issues

    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.

  19. docs/releasenotes/7.0.rst (Diff revision 1)
     
     
    Show all issues

    settings_local.py.

  20. docs/releasenotes/7.0.rst (Diff revision 1)
     
     
    Show all issues

    We should be able to reference this module directly up above, since Django's in the intersphinx. We can still give it this title.

  21. docs/releasenotes/7.0.rst (Diff revision 1)
     
     
     
    Show all issues

    Can we describe this briefly?

  22. docs/releasenotes/7.0.rst (Diff revision 1)
     
     
    Show all issues

    Let's use :term: here around "Local Site" so that users can learn what that means. It'll link to the glossary.

  23. docs/releasenotes/7.0.rst (Diff revision 1)
     
     
    Show all issues

    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).

  24. docs/releasenotes/7.0.rst (Diff revision 1)
     
     
     
     
    Show all issues

    Too many blank lines.

  25. docs/releasenotes/7.0.rst (Diff revision 1)
     
     
     
    Show all issues

    Feels like a word is missing here. "Fixed removing <what> when deleting ..." ?

    This would be subject to the same clarification as above.

  26. docs/releasenotes/7.0.rst (Diff revision 1)
     
     
    Show all issues

    Or on the CDN. Maybe "file storage"?

  27. docs/releasenotes/7.0.rst (Diff revision 1)
     
     
    Show all issues

    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.

  28. docs/releasenotes/7.0.rst (Diff revision 1)
     
     
    Show all issues

    We should use :guilabel: instead of quotes.

  29. docs/releasenotes/7.0.rst (Diff revision 1)
     
     
     
    Show all issues

    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 ...
    
  30. docs/releasenotes/7.0.rst (Diff revision 1)
     
     
    Show all issues

    "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".

  31. docs/releasenotes/7.0.rst (Diff revision 1)
     
     
    Show all issues

    Do we have docs we can link to instead of using quotes?

    1. Not that I see. We only have a page about the dashboard.

  32. docs/releasenotes/7.0.rst (Diff revision 1)
     
     
     
     
    Show all issues

    :guilabel: would be better for these.

  33. docs/releasenotes/7.0.rst (Diff revision 1)
     
     
    Show all issues

    We're using "diff viewer" here but "Diff Viewer" below. We should make sure we're consistent everywhere.

  34. docs/releasenotes/7.0.rst (Diff revision 1)
     
     
    Show all issues

    Let's link to the release notes for 6 here.

  35. docs/releasenotes/7.0.rst (Diff revision 1)
     
     
    Show all issues

    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?

  36. docs/releasenotes/7.0.rst (Diff revision 1)
     
     
     
    Show all issues

    Can we clarify this? I'm not sure what this is saying.

  37. docs/releasenotes/7.0.rst (Diff revision 1)
     
     
     
    Show all issues

    Can we say how it displayed incorrectly, so it's more clear what the wrong behavior was?

  38. docs/releasenotes/7.0.rst (Diff revision 1)
     
     
    Show all issues

    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.

  39. docs/releasenotes/7.0.rst (Diff revision 1)
     
     
     
    Show all issues

    Maybe specifically say "web browser caching conflicts."

  40. docs/releasenotes/7.0.rst (Diff revision 1)
     
     
    Show all issues

    Maybe "Review UIs now display an error ..."

  41. docs/releasenotes/7.0.rst (Diff revision 1)
     
     
     
    Show all issues

    "Extensions" gets its own top-level section after "New Features".

    1. I feel like this should go basically at the bottom. The vast majority of users probably care much more about bug fixes and usability/performance improvements than they do extension stuff, especially if we're going to fill it up with info about code deprecations and such.

  42. docs/releasenotes/7.0.rst (Diff revision 1)
     
     
     
     
    Show all issues

    We should link HideActionHook.

  43. docs/releasenotes/7.0.rst (Diff revision 1)
     
     
     
    Show all issues

    Just to help clarify this, maybe something like:

    Fixed invisible links to file attachments without captions set in :guilabel:`Admin UI -> Database -> File Attachments`
    
  44. docs/releasenotes/7.0.rst (Diff revision 1)
     
     
    Show all issues

    We should explain what this means. It's too vague.

  45. docs/releasenotes/7.0.rst (Diff revision 1)
     
     
    Show all issues

    Good opportunity for :guilabel:.

    Also, what kind of visual glitches?

  46. docs/releasenotes/7.0.rst (Diff revision 1)
     
     
    Show all issues

    :guilabel: would be good here, too.

    And other widgets below.

  47. docs/releasenotes/7.0.rst (Diff revision 1)
     
     
    Show all issues

    We have a couple Docker things spread out. This should all be in a Docker section.

  48. docs/releasenotes/7.0.rst (Diff revision 1)
     
     
     
    Show all issues

    This should go in New Features somewhere, rather than getting its own top-level section.

  49. docs/releasenotes/7.0.rst (Diff revision 1)
     
     
     
    Show all issues

    This section traditionally goes before Bug Fixes.

  50. docs/releasenotes/7.0.rst (Diff revision 1)
     
     
     
    Show all issues

    Performance Improvements goes before Usability Improvements.

  51. docs/releasenotes/7.0.rst (Diff revision 1)
     
     
    Show all issues

    Let's use :term: for Local Sites.

  52. 
      
david
david
maubin
  1. Ship It!
  2. 
      
chipx86
  1. Basically done, but there's a bit of organizational stuff left to help with reading through affected fixes.

  2. docs/releasenotes/7.0.rst (Diff revision 3)
     
     
     
     
    Show all issues

    I'd say this belongs more in Bug Fixes -> Integrations.

  3. docs/releasenotes/7.0.rst (Diff revision 3)
     
     
    Show all issues

    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.

  4. docs/releasenotes/7.0.rst (Diff revision 3)
     
     
    Show all issues

    For the reference, we can use:

    :doc:`Review Board 6 <6.0>`
    

    (Double-check that the reference works, but that should be it.)

  5. docs/releasenotes/7.0.rst (Diff revision 3)
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
    Show all issues

    Anything referencing something on a class needs to have that Class.thing as a title.

  6. 
      
david
chipx86
  1. 
      
  2. docs/releasenotes/7.0.rst (Diff revision 4)
     
     
     
    Show all issues

    General is usually first.

  3. docs/releasenotes/7.0.rst (Diff revision 4)
     
     
     
    Show all issues

    Debating on this, but maybe this should go in Reviews?

    We've also historically had a Review Requests section, but it may be a bit redundant here.

  4. 
      
david
chipx86
  1. Ship It!
  2. 
      
david
Review request changed
Status:
Completed
Change Summary:
Pushed to release-7.x (98786cb)