-
Notifications
You must be signed in to change notification settings - Fork 358
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
Defining process for adding new syntax #228
Comments
I think the step 1, 3, 4 is not necessary.
https://github.com/tc39/proposals serves this purpose well.
They can be implied from step 5 "A link to the full proposal" given that the proposal is the single source of truth. I am good with other steps. |
Yeah I think only steps 6-8 are necessary. |
My concern with leaving off the first few steps is that it's harder for us (ESTree) to track where we are relative to each proposal's stage. The TC39 proposals list is at least one click away, and doesn't tell us if we've already merged an experimental or final representation of a new syntax. If you don't want to go with a GitHub project, I'd at least suggest we have one issue for each proposal that we can merge experimental and final PRs against. Another benefit of having an issue per proposal is that it signifies to onlookers where we are with regard to developing ESTree representation for it. |
My concern with tracking proposals separately is in increased maintenance burden cost with low / unknown value. There's usually way more proposals in general than those that make it beyond experimental, and even for experimental ones it's not like we want to rush and define structures for everything right away, without knowing if anyone actually needs it / how it plays out with other proposals / etc.. As for stage 3 proposals minus the API changes - the one that we are explicitly interested in - they don't appear very frequently, and have already been easy enough to track IMO. |
I think there is value in having at least a tracking issue. As an example from last night. The TS4.0 beta has released with support for Short-Circuiting Assignment Operators. In planning out what work is required for typescript-eslint, I wanted to see if there was an AST already defined for it. This is what I did:
If there was a tracking issue, I'd have been able to see the status in a much clearer form with links to any PRs, the underlying TC39 spec, and from there it would have been easy to see that it was experimental and find the experimental AST. Issue tags would also make it easy to transparently track the status of the proposal for both TC39 stages, as well as ESTree stages. |
The https://github.com/estree/estree/tree/master/experimental serves well, the underlying TC39 spec is linked from each proposal title. I don't think another tracking issue can offer more values than maintaining cost.
We can briefly introduce on README about the folder structure: e.g. what
In Babel we use issue tags to issue/PR related to specific proposal. However I don't think it is of great value for a document-only project like ESTree. IMO the GitHub history link is sufficient: https://github.com/JLHwung/estree/commits/add-class-features/experimental/private-fields-in-in.md -- because the artifact of each proposal is a single markdown file. |
If I know what stage a proposal is in, then sure, I would have known to go straight to the The problem is that I had no idea what the TC39 stage is because I hadn't seen the spec. Without knowing the stage, I didn't know to look in the As another example, if I had missed a memo and didn't hear that a feature had moved to stage 4 and merged into the main spec, then I'd likely be confused that it isn't in the For someone like yourself - you work with babel and bleeding edge specs, so you're well versed in the TC39 process, the features that are being worked on, and can likely quickly and easily find those specs, or even know offhand the stage of a given spec. For someone like me that isn't - I would have to go googling to find the spec link to figure out the stage, or go clicking around this repo to attempt to find the spec for the feature. If this is catalogued as an issue, then there wouldn't be a question for anyone at all. Anyone can use the issue search here as a centralised place to locate the status and spec of the feature within ESTree's pipeline. |
I'd say you should always start at https://github.com/tc39/proposals as source of truth, which quickly gives you a stage. I wouldn't say you need to be "well versed in the TC39 process" to find the proposal in that structured list :) Maintaining a copy or even a derived data of that table creates more maintenance churn and still has a risk of going out of sync from time to time. As a result, you will still end up having to check the original source to figure out what the actual status of proposal is, which diminishes value of such copy as well. I'd much rather have a single source of truth that anyone can refer to. |
I didn't even know that page existed!!! (I doubt a lot of people do) I guess you're kind of proposing that the workflow be something like - open up estree, click a link to proposals, see that "logical assignment operators" is stage 3, go back to estree, open up the experimental folder, hope to find it in there (in this case, I would). Hypothetically, say that there wasn't an experimental spec that had been merged - where do I go next? As a consumer of ESTree, IMO having an issue to track the lifecycle of a proposal's implementation into this spec would be so much cleaner and remove all ambiguity from the process. I could easily use the issues as the record of what state each proposal is in its ESTree implementation. This would also make it trivial for a consumer to track if there are required AST changes for a proposal. |
Sorry for the late reply, been having some health-related challenges lately. So I think we're having a disconnect about the purpose of what I'm proposing (a tracking issue). The goal of having a tracking issue is not to simply mirror what is available at https://github.com/tc39/proposals, because I agree, that would just be maintenance overhead without any clear value. The goal is so we, as a project, can track our progress on making these changes. I do not find it easy right now to figure out if we've already addressed experimental changes or whether there has been a final node format submitted that would override the experimental format that has already been merged. Having a tracking issue is a signal to everyone (not just us) about where we are in the process of defining the AST for new features. If the primary concern is maintenance overhead, I believe the front-end of what I've described can be automated. I could foresee writing a script that runs each night against https://github.com/tc39/proposals and pulls in the relevant data. It could probably create issues, move them along in a GitHub project as their stage changes, and maybe leave a comment on the issue once a proposal reaches stage 3 to say "hey, it's time to define this officially!". I'm happy to work on this. |
At the moment, the process for adding new syntax is a bit haphazard. There are some implicit agreements, like experimental syntax goes in
experimental
and we don't debate much until a feature reaches stage 3, but it would be good to get organized and make the entire process explicit.As an example, here's what I envision as a starting point:
experimental
proposal referencing the issue associated with the proposalMy primary desire is to see that there's some traceability between the proposal, the experimental syntax proposal, and the final syntax proposal.
Again, this is just a suggestion for discussion, as having any well-defined process will make me happy. :)
The text was updated successfully, but these errors were encountered: