-
Notifications
You must be signed in to change notification settings - Fork 2.1k
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
Add documentation for initial versions #7485
Conversation
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
A very quick initial take here, but I'm very pleased by where this is headed!
One thing we're not great on is distinguishing consumer docs from contributor docs. We might be well-served by breaking this up a bit, to describe initial versions in the schema docs (alongside the ranged version info) and provide additional background and recommendations in the data guidelines.
The Node.js case is illustrative. In the schema docs, we could use the "subject to change" text you've already written. In the data guidelines we could say, "If you're adding new data, use 0.10.0
or later. If a feature was added in a version before 0.10.0
, use 0.10.0
anyway."
A couple notes to help your research in the comments. When this is further along, I can revisit this for nitpicking. 😄 Thank you!
Thanks for your very fast review! Glad I shared this early, so we can move things around.
Great point, forgot to look outside the Side note: I wonder if it would be worth having "consumer docs" and "contributor docs". Maybe these would be more approachable names than "data guidelines" and "schema docs".
Thanks so much! I knew these things once but forgot everything 😄
I think this is ready for you to nitpick away :) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Pretty close here. Some little suggests in line comments. Thank you, @Elchi3!
(Also, if you apply any of my suggestions, it may fail the Markdown linting. I didn't test them, sorry.)
Co-authored-by: Daniel D. Beck <[email protected]>
Great suggestions, thank you Daniel! 💯
Yeah, turns out markdown table formatting is enforced quite strictly here. (I think I prefer the compact notation, but |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Step one complete! Thank you, @Elchi3! 🎉
This attempts to add some docs about BCD's initial versions.
Background is #6861 in which we try to fix the initial version for Node.js data.
@ddbeck sharing this early and as a draft, so we can talk about whether this is going in the direction you imagined.
For Firefox Android and the Operas I actually need to dig a bit to understand why we have these initial versions. I'm sure there are good reasons, I just need to find them :)