Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Document an escape hatch for description reviews #1809

Open
ddbeck opened this issue Sep 19, 2024 · 2 comments
Open

Document an escape hatch for description reviews #1809

ddbeck opened this issue Sep 19, 2024 · 2 comments
Labels
documentation Improvements or additions to documentation

Comments

@ddbeck
Copy link
Collaborator

ddbeck commented Sep 19, 2024

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 ddbeck added the documentation Improvements or additions to documentation label Sep 19, 2024
@ddbeck
Copy link
Collaborator Author

ddbeck commented Sep 19, 2024

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
Copy link
Contributor

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation
Projects
None yet
Development

No branches or pull requests

2 participants