I agree. This has been one of the harder things to understand as I have started diving more into parsers and ASTs. Often times you have to go through a few different files and manually merge definitions to get the final, latest definition. And if you miss one of those files, you end up with a wonky picture of the AST, and won't know until it's too late.

Having a single "this is the complete, bleeding edge spec" or something would make digesting the repo so much easier.

Working on this

I'm wondering if this is a WIP.
Can we rely on https://github.com/j-f1/forked-estree/blob/add-latest/latest.md as a final spec?

@RReverser @JLHwung it looks like there was no formal discussion or decision on this. I'm definitely a big 👍 to having a single source of truth for the entire specification, but seems like we should make that decision explicit.

@nzakas I go with a single spec, like we did in Babel.

Maintaining a diff between different ES versions is a bit overhead. Can we tag certain commit with es2015, es2016? So if people are really interested at the diff, they can go with git-diff.

@JLHwung I like that idea, too.

@RReverser thoughts on just moving to a single spec instead of creating new files for each year?

Maintaining a diff between different ES versions is a bit overhead. Can we tag certain commit with es2015, es2016?

Hmm how would we do that cleanly for existing history? Or, even going forward, when some cleanups are applied to previous versions? That seems much trickier to maintain, and at least some of the parsers / consumers care about those versions and the differences between them more than about the "final" result.

I think a more realistic option is to always autogenerate "latest" Markdown like in @j-f1's attempt.

That seems much trickier to maintain, and at least some of the parsers / consumers care about those versions and the differences between them more than about the "final" result.

Do you have an example of this you can share? I definitely don't want to break any automation.

As a plan, I think we can accomplish the tag approach like this:

• Create a new file in specification/README.md (or whatever name we want, I don't care -- it just needs to be a new location) that is equal to the current es5.md
• Commit and tag that change as es5
• For each subsequent finalized edition, modify specification/README.md, commit and tag it.
• For future editions, we wouldn't tag the spec until it was finalized, so specification/README.md would always represent all stage 3 or later proposals plus the last published edition
• Remove the current es*.md files

I would think at that point the people interested in changes from one edition to the next would do a diff like es2019..es2020, for example.

I have put together a table that shows ESTree 2022 node types and their properties. Each reference is clickable and takes you to the definitions of the referenced type, sorted by ES version. While not strictly the same as a single specification, some of you might find it useful. (Table data is based on the formal data repository, which merges versions automatically.)