prql: Book & playground don't match the latest published version

Update from the meeting: - introduce stable branch which tracks the latest release + hotfixes/tweaks + docs changes, - most PRs are still merged into main (including docs of new features), - book & playground are released from stable branch,

We can look into having another release for the main branch published in parallel to current deployment, so there would be a “bleeding edge” for people to experiment with. For now, we can try to keep releases frequent.

I’m going to put names on things, because there are two comments enumerating options, so “Option 1” depends on which comment we look at!

• Latest commit — i.e. book & playground match the HEAD of main branch
• Latest release — i.e. book & playground match the most recent release

I’m all for the other improvements on the release cadence but I do think the most “correct” solution would be to either: a) either let the website’s visitors specify the version via a select (more difficult), or b) just always deploy the latest released version (easy).

having it match the current main also makes development easier for the project

This is obviously an important point, but I also think it’s probably a simple one to address. Other than running the playground with the code of your active local compiler branch, are there any other difficulties here that I’m missing? I’m sure we could figure those out (& I’m more than happy to help).

While releases e.g. at most every 2 weeks would be great for continuing the momentum of the project (irregardless of this issue), I think it’s incredibly user-unfriendly to have the docs & playground (not only the playground!) be incorrect for even a few days.

As we start to have more and more real, live use cases, these things will only get more important, and I’d hate for us to lose potential users because it externally looks like it’s a “broken thing”.

the first problem I see with that proposal: it doesn’t fulfil the original goal of this effort: the compiler in the playground doesn’t match the latest release, since it includes fixes. Do you agree?

Sorry, I didn’t explain it very well. The way I saw it, playground and docs would only be updated/deployed on releases, including patch releases. They therefore would match the latest release code.

book & playground are deployed from stable, either on every merge or only on releases.

The reason I included “on every merge” (to stable) in the above is that there was a concern expressed that without tests for the playground it is difficult to ascertain whether it’s working properly or not. So the way I pictured it is:

• a hotfix with documentation update is backported to stable
• the docs and playground are automatically deployed giving core contributors a chance to test the fix
• if everything is found to be working then a patch release is cut.

So there would indeed be a bit of drift between playground and latest release but it would likely be only minor since it’s just hotfixes and the patch release should follow soon.

If that’s undesirable then playground could only be deployed on releases. That would probably be my preference. The only downside is that if there’s a bug in the hotfix and the playground goes into a broken state then another patch release would have to follow immediately, but that could be ok.

Thanks for the terrific discussion on the Dev Call last Sunday. For those who weren’t on the call, here is a more fleshed-out version of my understanding of the discussion and comments from @max-sixty and @aljazerzen above. Comments appreciated.

Going forward, PRQL will maintain two important branches: stable and main.

• The stable branch tracks the latest released version of PRQL. It provides a base for people who wish to use it today. The Playground, Language Book, and CHANGELOG match the implementation of the stable release. In addition, any external integrations - VSCode extension, language bindings, etc. - all match the stable release. Only updates to the website or Language Book are permitted in the stable branch. No changes to the PRQL language or hot fixes/tweaks are allowed (those go into a new release).

  NOTE: PRQL is still an experimental project. We reserve the right to make the language better even if we must break previous queries. The PRQL language - even the stable branch - may (and probably will) change between releases as the language evolves. However, the stable release never changes once it has been released.

• The main branch receives PRs as development occurs. New features should be documented first in the “Unreleased” section of the CHANGELOG file, and in the Language Book/website as needed. It is an open question how the Web, Language Book, and external integrations will be made available to people who don’t have a development environment set up.

• From time to time (perhaps as frequently as every two weeks) we merge the main branch into the stable branch, and the new code becomes the next “released version”.

I’m not sure if full git flow workflow is necessary - it add some complexity where it is not yet needed.

A simpler alternative is what we have, but releasing patches (0.x.Y) by picking all non-breaking non-conflicting commits to a new branch.

The main problem here is that playground & book don’t match the latest release of the library and bindings. This is a huge problem for anyone who is not just “checking things out”.

If we go with option 1, the people that want to experiment with latest changes, would indeed have to wait for a release. This could be eased by:

• having another deployment of playground and book (which is not the easiest to set up),
• regular release cycle (i suggested every two weeks).

While releases e.g. at most every 2 weeks would be great for continuing the momentum of the project (irregardless of this issue), I think it’s incredibly user-unfriendly to have the docs & playground (not only the playground!) be incorrect for even a few days.

I agree with that.

I also got the impression that we only picked up some issues on release and deployment so I would vote in favour of doing some DEV/UAT/QA deployment somewhere which can be triggered on every merge to main.

I hear a consensus for putting out a release frequently. Before we design and build a lot of new machinery, let’s see if this release schedule minimizes the problems that have been identified.

Not easy but doable. The problematic part is that we build the whole website+book+playground in a single build for a commit and book requires prql-compiler for compiling PRQL snippets to SQL.