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

docs: Added 2to3.md #341

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Conversation

st-pasha
Copy link

@st-pasha st-pasha commented Dec 4, 2022

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

  • Please check if the pull request fulfills these requirements
  • Tests for the changes have been added (for bug fixes / features)
  • Docs have been added / updated (for bug fixes / features)
  • CHANGELOG.md has been updated to describe this change

To update the documentation on yarnspinner.dev, please visit the documentation repository.

  • What kind of change does this pull request introduce?
  • Bug Fix
  • Feature
  • 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

@McJones
Copy link
Collaborator

McJones commented Jan 17, 2023

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?

@st-pasha
Copy link
Author

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?

  • It gives the users a preview of what future holds.
  • It makes it easier for the team to plan the implementation of the features. For example, if there are 10 feature proposals currently in the queue, it could be decided that only 5 of them will make it into YS3.
  • It makes implementing features easier, because when there's the initial proposal, and then many-many-many pages of discussion afterwards, it may be hard to figure out what the ultimate conclusion was, and what actually needs to be implemented.
  • It gives heads up to the maintainers of non-official YS libraries about what features will be added in the future, so that they can start planning on how to support them.

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:

  • reference for what exactly needs to be implemented;
  • source for the "here's what's new in YS3" document;

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Proposal: Add a Yarn 3 language spec
2 participants