Open st-pasha opened 1 year ago
I am somewhat unsure as to this PR. Because we haven't locked a v3 spec what harm is there in just making changes directly to the spec document instead?
If the goal is for this to become part of a migration guide then the correct space for that to exist is the documentation site whose content can be found at YarnSpinnerTool/YSDocs.
Or have I misunderstood?
So, the idea here is the following: currently we have some language enhancement proposals, which are submitted as GitHub issues (as they should be). Once submitted, such proposal stays open for some time, there is some discussion, some back-and-forth. But for a very long time the status of a proposal remains uncertain: do we feel good about it? are there some unresolved questions? are we still thinking it over?
At some point though, the proposal gets implemented, a PR is merged, and then it's all done.
What I'm suggesting is to add an intermediate step into this process, whereas the proposal gets formally accepted before it can be implemented. And by "accepted" I mean that the author submits a PR with the description of the feature, that PR is reviewed one last time, approved by the team, and merged -- but this is a documentation only PR. At this point the original proposal issue can be closed.
After that, the new feature can be implemented, either by the original author, or by someone from the YS team, or by an outside contributor. There could be a separate issue tracking the implementation of the feature.
Why this extra step is beneficial?
Also, this extra step isn't much of a burden -- since the documentation for the new feature needs to be written anyway.
This being said, this PR isn't necessarily the best solution. It's merely a solution. Some projects use a different organizational structure: each proposal becomes a separate markdown document (for example: https://github.com/dart-lang/language/tree/master/accepted).
what harm is there in just making changes directly to the spec document instead?
The changes to a spec document should be done after the feature is implemented; whereas the proposal document should be written before the feature is implemented. This proposal document can be used as:
This PR adds a placeholder document where proposals can be accumulated before they are implemented, serving as a roadmap and allowing to easier coordinate changes across external YarnSpinner implementations.
Closes #334
To update the documentation on yarnspinner.dev, please visit the documentation repository.
What kind of change does this pull request introduce?
[ ] Bug Fix
[ ] Feature
[x] Something else
What is the new behavior (if this is a feature change)? This is a documentation-only change.
Does this pull request introduce a breaking change? (What changes might users need to make in their application due to this PR?) No