Release process

[max-sixty]

Now that some people are actually using PRQL, we should decide how to do releases.

Principles

• Low release latency. When someone makes a change, that should flow to users quickly — it's good for users and encouraging for contributors. There's very little weighing on the side of releasing slower — we have extensive tests, we can always roll-back if we make a mistake, no one is relying on it for production.
• Automated. Can we make this as automated as possible?

Tagging

We have the advantage of a monorepo (except for dbt-prql & pyprql, for their own reasons), but it means that it might too broad to just version everything based on a single unified repo tag; at least for patch versions — what do others think?

The upside is that it's very simple. The downside is that if we make a change to only prql-python and want to do a release, we get a new version of prql-compiler with zero changes. That would weigh more if we had something like dbt-prql here, because it's more than just a binding for prql-compiler.

Automation

• @rbpatt2019 & @charlie-sanders have set up some quite impressive automation in pyprql. It a bit heavier duty — each commit is labeled with whether it's a breaking change or not, and then it works out what version to use — but very manageable. (any thoughts?)
• Bumping the version in the source definition seems quite reasonable, particularly if we have different versions by library.
• We could attempt to publish to crates.io / PyPI / npm on every single merge, and allow them to fail if they're already created (though we'd need to parse the error message to ensure it didn't fail for another reason). At least for cargo, there doesn't seem to be a flag for "pass if it's already there".
  • Once pushed, a process could make the tags automatically (it needs to be that way around — we can't change the files based on pushing tags, since the tag would be attached to the old version)

Cadence

• We could do something like "nightly, assuming there's been a merge". Is there anything downstream that would be upset by that many releases? Maybe something with dependabot or a low latency, constantly filing PRs?
• The extreme would be "every merge"...

Any thoughts?

[mklopets]

a couple of thoughts:

• I quite like using conventional commits for commit messages in any case
• there's something called Release Please for automation on top of conventional commits
• I like the idea of versions being in sync across the different packages, so that prql-js 1.2.3 would match compiler 1.2.3, but obviously, changing the JS package shouldn't trigger a change for e.g. prql-python users
• what if the minor version matched between all packages, but patches wouldn't need to?
  • it's not ideal, but it's how @types/... TypeScript type packages are versioned
  • e.g. when react releases v18.1.0, @types/react would also release v18.1.0, but can then independently improve things in @types/react/v18.1.1 without the underlying react packages changing; [email protected] would then again come with an updated @types/react package
  • prql-js, prql-python etc would not technically follow semantic versioning themselves; their major+minor would match that of the used compiler version, but patch versions could also be released when they only have internal changes
  • the downside is that e.g. prql-js itself can change its return type, and this would just be seen as a patch release
• not sure how exactly this could be done, but could we decouple the JS/Python APIs from the bindings?
  • e.g. for JS, a prql-wasm npm package would always match the corresponding prql-compiler's version, but prql-js would just be a peer dependency of prql-wasm, and could independently have major version bumps (e.g. when the API changes to throw errors instead of return them under result.error)

[max-sixty]

https://github.com/prql/prql/pull/795 allows us to use cargo release, which I used manually the first time. The release workflow does the releases to PyPI & npm.

Next up:

• Decide how to do a changelog — automated vs manual? Ideally we'd have a draft one automatically produced — with authors etc — and be able to modify it
• Automate the release once https://github.com/crate-ci/cargo-release/issues/495 is solved (or we instead used Release Please). "Automate" might involve running a workflow manually.

---

what if the minor version matched between all packages, but patches wouldn't need to?

I think it would be OK to have the same version across all crates — the other crates are mostly bindings for prql-compiler, and it reduces the dimensionality of the problem if everything is on the same version. Maybe there's be a time where there are changes to prql-java but not the other crates, but I think that'll be quite rare. If it does happen, I think the suggestion of allowing patch numbers to advance at different speeds sounds great. cargo release seems to allow for this, but I'd be impressed if it handles the cross-dependencies.

there's something called Release Please for automation on top of conventional commits

This looks great, and allows for more oversight than cargo release seems to.

Do you have direct experience with it @mklopets ? (I'll check it out more if not).

I quite like using conventional commits for commit messages in any case

This does look good!

IIRC https://github.com/argoproj/argo-workflows might have a way of enforcing this.

I'm balancing two strong principles:

• Make everything as automated as possible
• Make it easy for people to start

I worry a bit that "force push an amended commit please, in this format" is actually quite difficult.

Can you think of ways where it's also easy? Including allowing things through with a warning if it's not exact?

[mklopets]

I think it would be OK to have the same version across all crates

I think that in an ideal world, we'd be able to semantically version all packages, which means separate versioning for each. See my prev comment's last point. Not sure if this is actually doable for all packages, though (it would for prql-js).

Do you have direct experience with it @mklopets ? (I'll check it out more if not).

Nope! For react-mapbox-gl, my biggest open source thing, version updates (it's only published on npm) were handled on a core contributor's machine, with them deciding whether to bump the patch, minor or major.

I worry a bit that "force push an amended commit please, in this format" is actually quite difficult.

If people with push access agree to always squash-merge (this can be enforced via repo settings) and to always make the squashed commit message follow the conventional commits standard, it could work. Then, most contributors wouldn't need to strictly follow this (though CONTRIBUTING.md could ask them to). Not sure if this makes a lot of sense when squashing together e.g. 3 feat-s, 2 fixes and 1 chore, though.

[max-sixty]

If people with push access agree to always squash-merge (this can be enforced via repo settings) and to always make the squashed commit message follow the conventional commits standard, it could work. Then, most contributors wouldn't need to strictly follow this (though CONTRIBUTING.md could ask them to). Not sure if this makes a lot of sense when squashing together e.g. 3 feat-s, 2 fixes and 1 chore, though.

Good point — we can enforce on the PR title rather than the commit message.

We may not need to have the merger responsible if there's a tool than can block a merge until the PR title is consistent.

We currently enforce squash merging (and encourage breaking up PRs!)

[max-sixty]

I've added an optional Conventional Commit check in https://github.com/prql/prql/pull/889

When https://github.com/orhun/git-cliff/issues/100 is closed, we can try automating the Changelog.

[max-sixty]

From https://github.com/PRQL/prql/pull/1350#discussion_r1057892244

If anyone knows a good way of generating changelogs with both a PR reference and the contributor, that would be v useful — anything we can do to raise the status of contributors is great (even though this time it's mostly @aljazerzen...).

(but without adding a burden on contributors themselves, e.g. changie)

Possibly I'll try git-ciff now

[max-sixty]

Possibly I'll try git-ciff now

Not quite there unfortunately, ref https://github.com/orhun/git-cliff/issues/132

[max-sixty]

https://github.com/googleapis/release-please is another option for automated changelogs. It has a really nice workflow where it keeps a PR open with a proposed changelog, and then doing a release is just merging that PR. It would do some of the work currently done by cargo-release, a tool which I'm very happy with and would be keen to retain.

[snth]

Also see this comment https://github.com/PRQL/prql/issues/1507#issuecomment-1399576956 on #1507 .

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.

[max-sixty]

This is mostly complete. I'll move the narrower automation question & todo to #2137