Skip to content

Add behavioral subfeature data guideline#26781

Merged
caugner merged 11 commits intomdn:mainfrom
ddbeck:behavioral-subfeature-guideline
Aug 26, 2025
Merged

Add behavioral subfeature data guideline#26781
caugner merged 11 commits intomdn:mainfrom
ddbeck:behavioral-subfeature-guideline

Conversation

@ddbeck
Copy link
Contributor

@ddbeck ddbeck commented May 13, 2025

Summary

This PR provides a general guideline for creating behavioral subfeatures.

Related issues

This continues a discussion started in #26605 (comment), while #26780 covers the partial implementation part of this.

This was partly inspired by #17352, but is narrower in scope.

@github-actions github-actions bot added docs Issues or pull requests regarding the documentation of this project. size:s [PR only] 7-24 LoC changed labels May 13, 2025
@github-actions
Copy link
Contributor

github-actions bot commented May 13, 2025

Tip: Review these changes grouped by change (recommended for most PRs), or grouped by feature (for large PRs).

Copy link
Contributor

@caugner caugner left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM so far.

Like #26780 already includes, some more examples might help comprehension.

@ddbeck
Copy link
Contributor Author

ddbeck commented May 14, 2025

@caugner I already mentioned 3 examples (css.properties.gap.flex_context and css.properties.gap.grid_context, and html.global_attributes.inert.ignores_find_in_page) and mention more specific guidelines (e.g., secure_context_required). Do you have something in mind here?

@ddbeck ddbeck requested a review from caugner May 15, 2025 11:11
@github-actions github-actions bot added size:m [PR only] 25-100 LoC changed and removed size:s [PR only] 7-24 LoC changed labels May 15, 2025
@ddbeck
Copy link
Contributor Author

ddbeck commented Jul 8, 2025

We discussed this on a special double-length BCD call today. Main takeaways:

  • This could use some improved wording (e.g., "readily" needs to be made more simple). I'll do this soon.

  • Reviewing past practice could help reviewers here. What do existing behavioral subfeatures look like? I said I'd try to generate a spreadsheet that lists the behavioral subfeatures.

  • It's hard to review existing behavioral subfeatures because they're hard to find. We discussed the idea of adding an (internal, at least to start) field like type: "behavior" to make it easier to find these features and lint certain aspects of them (for example, to require a description for all behavioral subfeatures).

Copy link
Member

@Elchi3 Elchi3 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM, thanks for working on this!

  • Maybe it is stated somewhere already but I think behavioral subfeatures should always have a description.
  • I have not yet looked at data but my feeling is that often these features don't age well because very often they are introduced as part of documenting browser release notes. Not sure we need dedicated guidance (or irrelevance criteria) right now, but maybe something to keep in mind for later.
  • If we see patterns of behavioral subfeatures, we should introduce dedicated guidelines (covered by the second paragraph you added), so that the data becomes more consistent.

Copy link
Contributor

@caugner caugner left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM.

Let's:

  • maybe add a list of specific guidelines to the second paragraph,
  • add a note about these guidelines being new
  • add this to the docs/index.md

@ddbeck
Copy link
Contributor Author

ddbeck commented Aug 19, 2025

This came up again on today's BCD call. I've made a few small changes:

  • Added text requiring a description.
  • Added links to all more-specific behavioral subfeature guidelines.
  • Added "feedback welcome" text at the top of the guideline. In today's call, we talked about adopting the guideline with the understanding it's sort of provisional. We talked about removing this text in 6 months (assuming the guideline survives that long).
  • Added this guideline to docs index.

@caugner and @Elchi3, I'd welcome re-review here. Thank you!

Copy link
Member

@Elchi3 Elchi3 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks Daniel, this looks good to me 👍

Co-authored-by: Claas Augner <495429+caugner@users.noreply.github.com>
@ddbeck
Copy link
Contributor Author

ddbeck commented Aug 26, 2025

From today's BCD call: this still needs a link to this PR, for symmetry with other guidelines. I'll try to get to this shortly.

@caugner caugner merged commit e0c83b3 into mdn:main Aug 26, 2025
6 checks passed
@ddbeck ddbeck deleted the behavioral-subfeature-guideline branch August 26, 2025 11:48
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

docs Issues or pull requests regarding the documentation of this project. size:m [PR only] 25-100 LoC changed

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants