search

crate / cratedb-sqlparse

Parsing utilities to validate and split SQL statements for CrateDB.
Apache License 2.0
4 stars 1 forks source link

Proper versioning #19

Closed amotl closed 1 week ago

amotl commented 1 month ago

We should also document somewhere (maybe in the README) the relation between the cratedb-sqlparse version and the CrateDB version itself, also I would add a small note on the release notes.

Originally posted by @surister in https://github.com/crate/cratedb-sqlparse/issues/3#issuecomment-2122215490

amotl commented 1 month ago

At https://github.com/crate-workbench/mlflow-cratedb, I am just following the version number of the upstream project. Does it make sense to apply the same paradigm on this project, so we don't need to maintain a corresponding version mapping manually?

amotl commented 1 month ago

For Python package versioning, we are using the excellent versioningit to reduce maintenance overheads. For NPM packages, I can't discover a corresponding package or mechanism yet. So, as a start, using traditional tools like npm-version will be good enough?

/cc @alexdametto

surister commented 1 month ago

Yes, I wouldn't complicate it any further, I'd propose to maintain a simple table in the readme like: Also adding a line in every Github release specifing the CrateDB version the package was compiled for

npm version github_tag CrateDB Version
0.0.3 0.0.3 5.7.1
0.0.2 0.0.2 5.6.4

If this is alright with you all I will write a small piece in the README and do the 5.7.1 release so the package can be used with the latest version :)

amotl commented 1 month ago

What do you think about my proposal at https://github.com/crate/cratedb-sqlparse/issues/19#issuecomment-2124663016, to not have any mapping table at all, and just follow the release numbering of the relevant upstream project instead, in this case, CrateDB?

surister commented 1 month ago

What about my proposal at #19 (comment), to not have any mapping table at all, and just following the release numbering of the relevant upstream project instead, in this case, CrateDB?

The thing is that it more complex and we might need to keep our own versions, for instance having two releases compiled for 5.7.1 makes sense, since there are many features that we currently haven't implemented.

amotl commented 1 month ago

I hear you, and still would like to keep thinking about decreasing maintenance and bookkeeping overhead from the very beginning, because it can easily kill your time budgets.

According to https://semver.org/, we could use a suffix [^1] to increase version numbers when needed, i.e. when needing to publish releases within the same cycle of CrateDB, without a version bump on it.

That would resolve the version collision issue you've mentioned. wdyt?

Examples:

[^1]: Build metadata MAY be denoted by appending a plus sign and a series of identifiers comprised of ASCII characters.

surister commented 1 month ago

For example: 5.7.1+001 has feature a and 5.7.1+002 has feature a+1 breaking change, we'd still need to keep track of things somewhere so an user that wants 5.7.1 can pick between 001 and 002 right?

amotl commented 1 month ago

After shuffling a few ideas in a private conversation, we may turn my proposal around, use regular semver-based project versioning like any other reasonable project, and add the CrateDB version as a suffix, to spare mapping tables.

Examples:

Depending on how that fits the bill (does not need to happen today or tomorrow), this, or another solution might be applied, or not. Please just go ahead, I need to go afk now.

proddata commented 1 month ago

I think it is rather rare that a feature gets removed from the dialect, i.e. most versions should be backwards compatible. Forward compatibility seems to be a bigger issue. Generally I assume it would be fine to support the latest stable, however be aware that tools would potentially not be fully compatible with nightly CrateDB builds then.

surister commented 1 week ago

After reading Georg's comment and thinking about it, I changed my mind. I was mostly worried about backwards comparability, cratedb-admin-alt has been in CrateDB's 5.4 for a while and I have extensively used for >5.4 and never had any issue, it sort of make sense since our SQL is stable.

So I wouldn't complicate it further, let's just keep a plain x.x.x semver versioning, and always build/support the latest CrateDB version.