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

Contributing docs: explain compat_features versus tags #1667

Merged
merged 4 commits into from
Sep 5, 2024

Conversation

ddbeck
Copy link
Collaborator

@ddbeck ddbeck commented Aug 26, 2024

Fixes #1633

@github-actions github-actions bot added the documentation Improvements or additions to documentation label Aug 26, 2024
docs/CONTRIBUTING.md Outdated Show resolved Hide resolved
Co-authored-by: James Stuckey Weber <[email protected]>
@autonome
Copy link
Collaborator

This removes the explanation of why this is optional, which should stay in some form:

In many cases, the corresponding browser-compat-data entries already map to the feature ID, and this is therefore not needed.

Also, this does not convey the intricacies of your answer in #1633:

The gist is that the contents of the authored YAML file (i.e., .yml) overrules other possible sources of data. This goes for status as well. If you provide a compat_features value, then the BCD tag is completely ignored. So either provide a complete compat_features list or none at all.

But maybe that's a lot for the table entry? Perhaps there's a better home for it, since this bit helped me understand the flow of the system as a whole better.

@ddbeck
Copy link
Collaborator Author

ddbeck commented Sep 2, 2024

But maybe that's a lot for the table entry?

Yeah, I think it's too much for the table. Really, we need a standalone fields reference. Maybe the guidelines.md file needs to become that.

That said, I tried to bring my comment into the section that follows, about dist files. This effect now gets at least three mentions:

  • In the table ("If compat_features is not set in…")
  • In the Feature dist files section ("The contents of the authored YAML file overrules all other implicit sources of data.")
  • In the Associate BCD keys with your feature section ("In this case, you don't need to explicitly list the BCD keys that your feature depends on.")

What do y'all think?

@ddbeck ddbeck requested a review from jamesnw September 2, 2024 11:01
Copy link
Collaborator

@jamesnw jamesnw left a comment

Choose a reason for hiding this comment

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

LGTM!

@Elchi3 Elchi3 merged commit a91dff1 into web-platform-dx:main Sep 5, 2024
3 checks passed
@ddbeck ddbeck deleted the tags-to-compat_features branch September 5, 2024 12:58
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

Successfully merging this pull request may close these issues.

Clarify how to use the compat_features key
4 participants