Document an escape hatch for description reviews

[ddbeck]

As a reviewer of new features, I've noticed that it's easy to be slowed by repeated rounds of minor revision on descriptions. Often, the rest of a PR can be settled quickly except the description.

I propose documenting a convention so that we can move forward with "good enough" descriptions, but make them findable for further review and revision PRs. Something like this:

PR reviewers: If your only feedback is on descriptions or you're not the first reviewer, then consider one of this options:

• Leaving optional suggestions with an approved review. Don't block PRs on descriptions unless its strictly necessary.
• Suggesting appending <!-- good enough --> to the end of a description and (if possible) applying the suggestion and merging. Then you can revisit the description yourself, in a follow-up PR.

PR authors: Respond to the first reviewer's first round of comments or suggestions on descriptions. On subsequent rounds or reviewers, you can append <!-- good enough --> to the end of the description and move on, or merge if there is not other discussion.

By including the comment in the description, it becomes query-able with tools like yq. It's also possible for us to filter such comments of the built output.

Possible follow-on tasks:

• Open an issue calling for review and rewrites with a "good first issue"

Alternatives I considered:

• Using a YAML comment instead (not as queryable as an HTML comment in the description string)
• Not doing this and accepting longer review times

[ddbeck]

Some good ideas @tidoust mentioned in the WebDX call today:

• recording the date that the flag comment was set (so we can schedule follow-ups)
• using an actual internal editorial field for recording this

On the latter point, that might be a nice thing. I could easily imagine an editorial key (or keys?) for internal-use data. Something like this:

editorial-description-good-enough: 2024-09-19

It's a little heavier weight, but more formal and adds a new dimension for querying the data.

[captainbrosset]

Pros of this proposal:

• It's faster to get new features in.
• We get a way to track which features need more work on descriptions.
• It's a good way to file "good-first-bug" issues and attract new contributors to the project.

Cons:

• Iterating on a good description has helped me refine features a few times. Clearly articulating what you think the feature does for developers can help find the right BCD keys to add or to ignore.

So, while making it easier/faster to author and review features is a good goal to have, we should make sure we create great features, and I don't expect this proposal to reduce the time it takes to merge PR by an order of magnitude.
Overall, I'm still supportive of this, but on the condition that we do track the features that need more description work (either by using the HTML comment, or the extra yaml field).