Managing releases and version numbers here vs Base

[c42f]

We need a clear procedure for managing JuliaSyntax releases.

This is currently awkward because we're basically versioning two APIs:

1. There's the JuliaSyntax package version for our SyntaNode AST and APIs like parsestmt(), etc. Next release will be Release 1.0.0 #472, we have a couple more breaking changes to make.
2. There's the version number for Expr-related functionality used by Base - this is semantically just Julia version number (apart from bugfixes specific to this package)

These two versions serve really different purposes and may not even have compatible orderings.

For example, #456 made a change to operator kinds in the AST which is completely invisible to Expr, but is a breaking change to the JuliaSyntax API and should be followed on with #474 for consistency before the next JuliaSyntax release. Conversely, the new functionality introduced by #456 is only a feature addition.

There's one big mitigating factor: JuliaSyntax's parsestmt() has a version which is independent of Julia's VERSION, so in principle any new version of JuliaSyntax can be used with an old version of Julia.

I hope that getting to a solid JuliaSyntax 1.0.0 release soon will get things less diverged and easier to manage.

There's one extra factor - for the purposes of maintaining a Julia LTS, we might want an LTS branch of JuliaSyntax itself to support the associated Julia LTS. This is partly a sign that our testing still needs work but being conservative with patches for the LTS is probably a good thing.

What to do about the mess?

How about we do the following:

• Get JuliaSyntax to 1.0 asap, and try to cut releases off main more often. If we need a 2.0 soon, so be it (we will; JuliaSyntax's API will keep evolving, it's not close to done yet.
• Potentially, keep an release-lts-1.10 branch for Julia 1.10 LTS
• Use the latest JuliaSyntax releases when vendoring into Julia Base dev versions

This last one is a bit of an unknown. We don't want to hold Julia Base development up by having JuliaSyntax's release cycle stuck like it has been lately. So alternatively we could just tag JuliaSyntax with a Base-specific version tag at any time that someone bumps the vendored version in Base. But then we have even more versions flying around and that seems bad too.

Tooling

• There's a hacky script I use for bumping the vendored version in Base. This should at least go in this repo in the tools directory. Or maybe in Base itself.
• It'd be nice to have regression tests of JuliaSyntax against itself for both SyntaxNode and for Expr. @LilithHafner had some good ideas about this (see Better corpus testing #446). At some point we also need to stop testing against the flisp parser as the source of truth. Especially as we add features, but also because fixing bugs in things like line numbers makes maintaining the code which compares with the flisp parser pretty tedious and error prone.
• We really need better tooling for regression testing against the corpus of Julia code in the package ecosystem. We should be doing this for Expr parsing (at least) each time we release a JuliaSyntax version. At the moment this is a problem because downloading and unpacking the entire package ecosystem is slow. And we still test against the flisp parser which is a problem because there are exceptions I manually look through.

[Keno]

It seems impractical to me to require full sem-ver compatible releases of JuliaSyntax before we can bump the version in Julia. No other stdlib works that way.

[c42f]

Yeah so we could just tag JuliaSyntax main branch with a Base-specific tag when people want to bump it. Or not bother tagging it at all and just have a script to update the vendored version in Base. You asked about tagging in #465 so I maybe went off on a tangent worring about how versions interact 🤷‍♀️

Just bumping from main allows Base dev to go faster but it doesn't solve the testing issues I've mentioned above - currently there's some manual steps for the full syntax regression tests. I guess pkgeval can stand in for that on the downstream side for now.