Merge pull request #39 from chdb-io/docs/engine-pin-names-chdb-core-not-clickhouse

Say the engine pin names a chdb-core release, not a ClickHouse one

Author: ShawnChen-Sirius

.github/scripts/check-engine-pin.sh

@@ -10,13 +10,15 @@
 # The first two disagreeing means the engine a build links against is not the one
 # the script put there, which surfaces as missing symbols or as behaviour that
 # does not match the version anyone thinks they are running. The third disagreeing
-# is quieter and worse: the crate says it carries one ClickHouse and carries
-# another, and a crates.io version cannot be replaced — only yanked — so it says
-# the wrong thing permanently.
+# is quieter and worse: the crate names one engine and carries another, and a
+# crates.io version cannot be replaced — only yanked — so it says the wrong thing
+# permanently.
 #
-# Only vX.Y.Z and vX.Y.Z-rc.N are accepted. Those are the two shapes chdb-core
-# tags and the two the other bindings can parse, so a pin outside them is either a
-# typo or a tag nothing downstream can consume.
+# Only vX.Y.Z and vX.Y.Z-rc.N are accepted, which is chdb-core's tag shape: X.Y is
+# the ClickHouse minor line the release sits on and Z is chdb-core's own counter.
+# ClickHouse tags its own releases with four fields, so a four-field pin names a
+# tag in the wrong repository rather than a newer engine. Anything else is a typo
+# or a tag the other bindings cannot parse.
 
 set -euo pipefail
 

.github/workflows/engine-release-check.yml

@@ -177,7 +177,7 @@ jobs:
             echo "$current → \`$ENGINE_VERSION\` in all three places that carry it:"
             echo "\`update_libchdb.sh\`, \`build.rs\`, and \`engine\` under"
             echo "\`[package.metadata.chdb]\` in \`Cargo.toml\`, which is what tells a user"
-            echo "of the published crate which ClickHouse is inside it."
+            echo "of the published crate which engine is inside it."
             echo
             echo "$RUN_URL"
             echo

Cargo.toml

@@ -54,11 +54,17 @@ name = "arrow_stream_roundtrip"
 required-features = ["arrow"]
 
 [package.metadata.chdb]
-# The chdb-core release this crate builds against. The crate version above says
-# nothing about it — 1.4.0 is this crate's own numbering — so without this there
-# is no way to tell which ClickHouse a published version carries short of reading
-# build.rs at the matching tag. Here it travels with the package and can be read
-# from `cargo metadata` or the crates.io API.
+# The chdb-core release this crate builds against. This is a chdb-core release
+# number, not a ClickHouse one: X.Y is the ClickHouse minor line the release sits
+# on and Z is chdb-core's own counter, so v26.7.0 carries some ClickHouse 26.7
+# rather than a ClickHouse 26.7.0. The chdb-core release notes for the tag name
+# the exact upstream build.
+#
+# The crate version above is unrelated — 1.4.0 is this crate's own numbering — so
+# without this key there is no way to tell which engine a published version
+# carries short of reading build.rs at the matching tag. Here it travels with the
+# package, readable through `cargo metadata`, the .crate archive or the docs.rs
+# source view; the crates.io API does not expose it.
 #
 # .github/scripts/check-engine-pin.sh keeps it in step with build.rs and
 # update_libchdb.sh, which are what actually fetch the engine.