Proposal: Add a Yarn 3 language spec

[st-pasha]

Introduction

The Yarn 2 language spec was published and frozen more than a year ago. Since then, there were many new features added to the language, and there are additional ones that are planned to being added. In order to properly document those new features, and to express the intention to add new features in the next version of the language, I'm suggesting to create 2 new documents:

• 2to3.md which would contain the list of current or future changes in Yarn 3;
• yarn3.md which would be a work-in-progress document for the complete language spec of Yarn 3.

Rationale

1. Allow users to have a clear view of which features have been added to the language.
2. Serve as a roadmap for which features are planned to be added.
3. Streamline the process of making improvements to the Yarn language. Currently, when a proposal is made, it is considered "accepted" when it has an active implementation for the Yarn compiler. But that doesn't have to be the case: the process of deciding that certain feature ought to be added, and actually adding it, can be separated.
4. Allow Yarn- community projects to work on supporting Yarn 3 features in parallel with the main project. A community project can start implementing the support for a new feature as soon as it is specced, which could allow it to not fall too far behind from the mainstream Yarn.
5. There are changes that can be done to Yarn 2 spec that are not necessarily new features, but rather clarifications for existing features, or simply filling the gaps. The new spec3.md file would be a good place to gradually improve such aspects.

Detailed design

• Two new documents 2to3.md and yarn3.md in the Documentation directory. The documents both bear clear notices that they are work-in-progress.
• At some future day when the new spec is ready to be published, these documents will become "frozen" just like the current Yarn2 document.
• Features that currently exist in the language but are not documented in the Yarn2 spec (like markup, or functions), can get added into the yarn3 doc as simple "documentation improvement PR"s.
• Features that were added after September 30, 2021 will get documented both in 2to3 and in yarn3.
• New proposals for language improvements, can get added into the 2to3 doc (clearly marked as a future feature), once there is a consensus for how it should look like and what it should do.
• New proposals could get some kind of IDs, so that external projects can easily track which ones they support and which ones they don't.

Acknowledgments