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

Add documentation for initial versions #7485

Merged
merged 5 commits into from
Nov 25, 2020
Merged

Conversation

Elchi3
Copy link
Member

@Elchi3 Elchi3 commented Nov 24, 2020

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

@github-actions github-actions bot added the docs Issues or pull requests regarding the documentation of this project. label Nov 24, 2020
Copy link
Collaborator

@ddbeck ddbeck left a 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!

@github-actions github-actions bot added the schema Isses or pull requests regarding the JSON schema files used in this project. label Nov 24, 2020
@Elchi3
Copy link
Member Author

Elchi3 commented Nov 24, 2020

A very quick initial take here, but I'm very pleased by where this is headed!

Thanks for your very fast review! Glad I shared this early, so we can move things around.

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.

Great point, forgot to look outside the docs/ folder. (silly past me who put this in the schema/ folder). I completely agree it belongs in the "consumer docs" next to ranged versions. I moved it there.

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

A couple notes to help your research in the comments.

Thanks so much! I knew these things once but forgot everything 😄

When this is further along, I can revisit this for nitpicking.

I think this is ready for you to nitpick away :)

@Elchi3 Elchi3 marked this pull request as ready for review November 25, 2020 10:58
Copy link
Collaborator

@ddbeck ddbeck left a 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.)

@Elchi3
Copy link
Member Author

Elchi3 commented Nov 25, 2020

Great suggestions, thank you Daniel! 💯

(Also, if you apply any of my suggestions, it may fail the Markdown linting. I didn't test them, sorry.)

Yeah, turns out markdown table formatting is enforced quite strictly here. (I think I prefer the compact notation, but npm run fix is helpful and gets things done anyways)

Copy link
Collaborator

@ddbeck ddbeck left a 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! 🎉

@ddbeck ddbeck merged commit 781e7b2 into mdn:master Nov 25, 2020
@ddbeck ddbeck changed the title Data guideline for initial versions Add documentation for initial versions Nov 25, 2020
@Elchi3 Elchi3 deleted the initial-versions branch November 25, 2020 13:31
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. schema Isses or pull requests regarding the JSON schema files used in this project.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants