There was also a bug fix for the rbt review add-diff-comment command. You can add this to the bug fix list:

Fixed a bug where :rbtcommand:rbt review add-diff-comment would always add the comment to the last

  file in the diffset, instead of the specified file.

We should mention that web-based login does not currently support authenticating remote systems (e.g. when a user SSHs into a remote server and tries to do rbt commands there). But we're planning on adding that in a future release.

What really happens is an API token is generated and used once to authenticate RBTools. Then upon that authentication, a session cookie is created and stored, and that session is used for future requests.
I'd say let's just take out this sentence, its only giving implementation details anyway.

Wrap .reviewboardrc in backticks.

Ship It!

Ship It!

Biggest piece of feedback here is that we're only documenting the user-facing features, but since RBTools is an API that's built upon, it's crucial we document any and all API changes as well. I don't know if I caught everything, but I made my best attempt.

We have some performance improvements for posting review requests (the one where you limited the amount of data we fetch when posting).

We added the rbtools.utils.mimetype module, which also needs to be included in docs/api/coderef/index.rst.

We added rbtools.utils.browser.open_browser().

We added RBClient.user_agent to access the agent we compute, and a default rbtools.api.request.RBTOOLS_USER_AGENT.

We added BaseSCMClient.get_file_content() and get_file_size() with suitable capability flags.

We added Capabilities.get_capability().

We added better error messages when trying to log in using an expired or invalid API token. This isn't dependent on the --api-token addition.

We fixed bugs that could lead to a crash or data corruption when a command tries to write both Unicode and byte strings. This is the OutputWrapper change.

We added a strings_only= argument to force_unicode() and force_bytes(), which may matter to custom code.

Command base classes have been moved into rbtools.commands.base. Old classes are deprecated.

`DiffFile

We added the DiffFileAttachmentListResource specialization for uploading binary files.

We deprecated execute() in favor of run_process().

We added rbtools.config for looking up configuration options, which is important for custom commands or consumers of the API. This is available on BaseCommand.config.

We removed the setuptools dependency and added packaging, importlib-metadata, and importlib-resources (versions in setup.py).

We added a dependency on housekeeping.
By the way, we need to bump the dependency version to the latest release. It's currently set to an alpha release.

We need to make sure any new modules are documented in rbtools/api/coderef/index.rst. I

We added JSONOutput.raw for custom code to get the raw results of a command's JSON output when calling the command programmatically. This is structured data, not serialized to a string.

This is missing the instructions block at the top of the release notes.

There's a bunch of deprecation changes that are going to be important for people using the API or building custom commands. These are important to include. Breaking down the ones I noticed:
We removed deprecated methods (or fulfilled deprecated expectations where indicated).

rbtools.find_server_repository_info() from client classes
rbtools.utils.match_score
rbtools.utils.review_request.get_possible_matches()
rbtools.utils.review_Request.num_exact_matches()
rbtools.utils.review_Request.find_review_request_by_change_id()'s repository_info and repository_name arguments.
rbtools.utils.review_Request.guess_existing_review_request()'s repository_info, repository_name, guess_summary, and guess_description arguments. submit_as is now required.
BaseCommand.initialize_scm_tool's require_repository_info argument.
BaseCommand.setup_tool()
BaseCommand.get_server_url()
APICache.__init__'s urlopen
ResourceDictField's iterfields(), iteritems().
rbtools.clients.SCMClient (in favor of rbtools.clients.base.scmclient.BaseSCMClient)
BaseSCMClient.scmclient_id is now always required
BaseSCMClient.entrypoint_name
rbtools.utils.checks.check_gnu_diff()
rbtools.utils.checks.is_valid_version()
rbtools.utils.filesystem.CONFIG_FILE
rbtools.utils.process.log_command_line()


We added deprecations/changes:

rbtools.utils.review_request.find_review_request_by_change_id() deprecated non-keyword-only args
rbtools.utils.review_Request.guess_existing_review_request() deprecated no-nkeyword-only args, and deprecated api_client

The following require keyword-only arguments now:

RepositoryInfo.__init__()
BaseSCMClient.get_tree_matches_review_request()
BaseSCMClient.diff()
BaseSCMClient.apply_patch()
BaseSCMClient.create_commit()
BaseSCMClient.delete_branch()
BaseSCMClient.merge()
BaseSCMClient.apply_patch_for_empty_files()
BaseSCMClient.amend_commit_description()
rbtools.utils.diffs.filename_match_any_patterns()
rbtools.utils.diffs.filter_diff()
rbtools.utils.diffs.normalize_patterns()
rbtools.utils.diffs.remove_filenames_matching_patterns()
rbtools.utils.filesystem.make_tempfile()

Important for calling and implementing these.

ClearCase had some major updates. Might be worth documenting, in case of regressions.

One blank link between these sections, since there's no content between the sections.

Let's add a link to our e-mail address.

This is missing a trailing period.

We should mention the WEB_LOGIN setting.

Let's link to the .reviewboardrc docs instead.

Do we have any docs for this that we can link to?
If not, let's file tasks to start making this happen. We need to get better at this part of it.

Comma before "which".

Comma before "which".

To confirm, does this link correctly?

Let's break this into our standard summary line / description for release notes. Easier to scan for the changes.

Let's link to the TFS-Git docs.

This was a super recent change that slipped in, can you add it to the bug fixes list.

For the new API changes sections, can you build the docs and check each item for consistency? There's a bunch of syntax errors and broken roles in there right now.

For a future TODO: We really need to document these payloads thoroughly.

These should always list the version ranges.

Installation is always before Compatibility in our release notes.

This is going to be 5.x, rather than 5.0.

Can you verify this works without a mailto:?

These are missing reference roles and backticks.

This has an extra backtick at the end
We also want to explicitly title it BaseCommand.initialize_scm_tool().

This isn't going to show the class name as-is, just __init__.

These should still use roles.

For the methods, don't forget to put () after the method name in the title, so it appears like a :py:meth normally does.

Literals need two backticks.

Ship It!

Missing trailing periods.

This needs the Capabilities.get_capability() title, since it'll just link as get_capability().

In our docs, we can wrap at any . within the reference to avoid the single-word lines and the long reference lines.

The next bullet point got inlined.
Let's make sure we have a blank line between every bullet point, even for one-liners, to stay consistent.

We aren't titling this, so no (). This should be the module path.
Same with several below.

No () here. This is a constant.

review_Request -> review_request.

These are all missing () for the titled method name.

Let's wrap these (and any below that are too long).

__init__ -> __init__() in the title.

Missing a () in the title.