JuliaLang / JuliaLang/JuliaSyntax.jl

Managing releases and version numbers here vs Base

Open
#481 2 comments 0 reactions 0 assignees View on GitHub
Dominant language
Julia
Stars
293
Forks
50
PR merge metrics
No merged PRs in 30d

Description

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 #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 #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.

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.