From 90f5b63cfbf88d714be51c48c7a1bac5625e117a Mon Sep 17 00:00:00 2001 From: Taewoon Kim Date: Thu, 12 Nov 2026 09:38:34 +0900 Subject: [PATCH] Docs: quickstart output on 26.11.1.post2, facets pre-release hint, concurrency caveat, ci.adoc bold (refs #365) quickstart.adoc: its three scripts ran on Python 3.12 against arcadedb-jvm and arcadedb 26.11.1.post2 (extracted from the page and run with uv); both packages printed exactly the output on the page, so the sentence now says that and the old-name remark is gone. facets.adoc and columnar-index.adoc: an install hint for the pre-release wheels (checked with 26.12.1.dev2 of both packages: the COLUMNAR index and a FACETS clause run; a plain uv add installs 26.11.1.post2, --prerelease allow installs 26.12.1.dev2). concurrency.adoc: a caveat that the probes ran on older builds and were not run again on 26.11.1.post2. ci.adoc: `docs/**`, `*.adoc` and `LICENSE*` are wrapped as passthrough in code spans, as the native-paths bullet is. Co-Authored-By: Claude Sonnet 5.5 --- docs/modules/ROOT/pages/development/ci.adoc | 4 ++-- docs/modules/ROOT/pages/how-to/columnar-index.adoc | 2 +- docs/modules/ROOT/pages/how-to/concurrency.adoc | 2 +- docs/modules/ROOT/pages/how-to/facets.adoc | 2 ++ docs/modules/ROOT/pages/quickstart.adoc | 3 +-- 5 files changed, 7 insertions(+), 6 deletions(-) diff --git a/docs/modules/ROOT/pages/development/ci.adoc b/docs/modules/ROOT/pages/development/ci.adoc index 1772e27..eefbda0 100644 --- a/docs/modules/ROOT/pages/development/ci.adoc +++ b/docs/modules/ROOT/pages/development/ci.adoc @@ -18,7 +18,7 @@ Each package has one test workflow and one release workflow: The release workflows call the test workflows (`workflow_call`) and then publish; see xref:development/release.adoc[Release]. `release-notes.yml` runs after both of them have succeeded for a tag and creates the GitHub Release (and closes the milestone of a final release). Two workflows test the `arcadedb-jvm` package: `test-jvm.yml` builds a wheel and runs the unit tests, and `test-python-examples.yml` runs the scripts in `examples/`. Both build the wheel once for each platform, on a native runner of that platform (`Build arcadedb-jvm wheel ()` and `Build wheel for examples ()`), and install that one file into each Python they test. `test-native.yml` builds and tests the `arcadedb` (native) package; see <>. -The workflow `docs.yml` builds these docs (the Antora component in `docs/`) as a site of its own with `docs/antora-playbook.yml`, on every pull request and push to `main` that changes `docs/`, and attaches the site as the `docs-site` artifact. Download it from the run to read a page as it will render. The test workflows ignore `docs/**` and `*.adoc`, so for a docs-only pull request this job is the only check. A warning fails it: a broken `xref:`, a misspelled `+{attribute}+`, an AsciiDoc syntax problem. Pages link into the main ArcadeDB manual as `+{arcadedb-docs-url}/+`, not with an `arcadedb::` xref, which the component on its own cannot resolve. To build the site locally, run `npx -p @antora/cli@3.2.1 -p @antora/site-generator@3.2.1 antora docs/antora-playbook.yml` from the repository root and open `docs/build/site/index.html`. +The workflow `docs.yml` builds these docs (the Antora component in `docs/`) as a site of its own with `docs/antora-playbook.yml`, on every pull request and push to `main` that changes `docs/`, and attaches the site as the `docs-site` artifact. Download it from the run to read a page as it will render. The test workflows ignore `+docs/**+` and `+*.adoc+`, so for a docs-only pull request this job is the only check. A warning fails it: a broken `xref:`, a misspelled `+{attribute}+`, an AsciiDoc syntax problem. Pages link into the main ArcadeDB manual as `+{arcadedb-docs-url}/+`, not with an `arcadedb::` xref, which the component on its own cannot resolve. To build the site locally, run `npx -p @antora/cli@3.2.1 -p @antora/site-generator@3.2.1 antora docs/antora-playbook.yml` from the repository root and open `docs/build/site/index.html`. The package supports four platforms and four Python versions (3.11 to 3.14). That is 16 combinations. The organisation shares one runner limit with ArcadeData/arcadedb, so each macOS or Windows job delays the upstream jobs too, and not every combination runs. @@ -71,7 +71,7 @@ The dev-engine bump after each release, described in xref:development/release.ad == Other rules -* A pull request that changes only documentation (`docs/**`, `*.adoc`, `CLAUDE.md`, `examples/README.md`, `LICENSE*`) runs nothing. +* A pull request that changes only documentation (`+docs/**+`, `+*.adoc+`, `CLAUDE.md`, `examples/README.md`, `+LICENSE*+`) runs nothing. * A draft pull request skips the platform jobs. Marking it ready for review starts them. * A new push to a pull request cancels the run it replaces. A run on `main` is never cancelled. * A JVM crash in an example leaves a HotSpot `hs_err_pid.log`. `test-python-examples.yml` uploads these files as the artifacts `jvm-crash-logdir--py` and `jvm-crash-cwd--py` (issue 352); read them before you re-run a red example leg. diff --git a/docs/modules/ROOT/pages/how-to/columnar-index.adoc b/docs/modules/ROOT/pages/how-to/columnar-index.adoc index 9acd40b..2ba2d93 100644 --- a/docs/modules/ROOT/pages/how-to/columnar-index.adoc +++ b/docs/modules/ROOT/pages/how-to/columnar-index.adoc @@ -3,7 +3,7 @@ // Sources: ArcadeDB 26.12.1: GlobalConfiguration.java (COLUMNAR_*), AlterDatabaseStatement.java, ColumnarGroupByStep.java, ColumnarCrashRecoveryTest.java. The statements about Python are pinned by tests/test_columnar_index.py, which runs on arcadedb-jvm and on the native arcadedb. -A `COLUMNAR` index keeps a column projection of a type next to its records. The engine applies, flushes and merges it in threads of its own, and the `FACETS` clause and `GROUP BY` read it. It needs engine 26.12.1 or later: an older engine refuses `CREATE INDEX ... COLUMNAR` with `Index type 'COLUMNAR' is not supported`. The facets themselves are read with `ResultSet.facets`, which xref:how-to/facets.adoc[Faceted queries] shows kind by kind. +A `COLUMNAR` index keeps a column projection of a type next to its records. The engine applies, flushes and merges it in threads of its own, and the `FACETS` clause and `GROUP BY` read it. It needs engine 26.12.1 or later: an older engine refuses `CREATE INDEX ... COLUMNAR` with `Index type 'COLUMNAR' is not supported`. Until 26.12.1 is released, a pre-release wheel brings such an engine: see xref:how-to/facets.adoc#older-engine[An older engine]. The facets themselves are read with `ResultSet.facets`, which xref:how-to/facets.adoc[Faceted queries] shows kind by kind. The index is a statement, so it is the same on both builds: diff --git a/docs/modules/ROOT/pages/how-to/concurrency.adoc b/docs/modules/ROOT/pages/how-to/concurrency.adoc index a658637..aadfb05 100644 --- a/docs/modules/ROOT/pages/how-to/concurrency.adoc +++ b/docs/modules/ROOT/pages/how-to/concurrency.adoc @@ -5,7 +5,7 @@ This page covers what is specific to the Python bindings: which calls work from == How to read the numbers -Every number on this page, except the ratios in <>, comes from probe scripts that were run on 2026-10-24 on one Linux x86_64 machine. The setup of each probe is next to its numbers. The scripts and their raw logs are not part of this repository yet. +Every number on this page, except the ratios in <>, comes from probe scripts that were run on 2026-10-24 on one Linux x86_64 machine. The setup of each probe is next to its numbers. The builds in the table below are older than the current release, 26.11.1.post2, and the probes were not run again on it, so read each number as a measurement of the build that produced it. The scripts and their raw logs are not part of this repository yet. [cols="1,3,2"] |=== diff --git a/docs/modules/ROOT/pages/how-to/facets.adoc b/docs/modules/ROOT/pages/how-to/facets.adoc index 0710eb1..bc51a9e 100644 --- a/docs/modules/ROOT/pages/how-to/facets.adoc +++ b/docs/modules/ROOT/pages/how-to/facets.adoc @@ -650,6 +650,8 @@ has_facets = engine_version(db) >= (26, 12, 1) A snapshot or a build suffix of the version is dropped, so `26.12.1-SNAPSHOT` counts as 26.12.1. The https://github.com/ArcadeData/arcadedb-python/blob/main/examples/30_columnar_facets.py[example] makes this check, and prints one line and stops when the engine is too old. +Until 26.12.1 is released, a pre-release wheel can bring an engine that has both features. A plain `uv add {native-pkg-name}` installs the final release, which does not, so ask for the pre-release: `uv add --prerelease allow {native-pkg-name}` (or `{jvm-pkg-name}`), or name its version, for example `uv add "{jvm-pkg-name}==26.12.1.dev2"`. Version `26.12.1.dev2` of both packages accepts the `COLUMNAR` index and the `FACETS` clause. The check above tells you what an installed build has. xref:installation.adoc[Installation] says more about pre-releases. + == Known limits * The extremes of a negative zero come back as `0.0`, and `0.0 == -0.0` in Python, so a `MIN` or `MAX` facet cannot tell them apart. A `DISTINCT` counts `-0.0` and `0.0` as one value. diff --git a/docs/modules/ROOT/pages/quickstart.adoc b/docs/modules/ROOT/pages/quickstart.adoc index 1958864..f82bcfb 100644 --- a/docs/modules/ROOT/pages/quickstart.adoc +++ b/docs/modules/ROOT/pages/quickstart.adoc @@ -20,8 +20,7 @@ This page builds a small database from scratch. You need one of the two packages See xref:which-package.adoc[Which package?] if you are not sure. If you are not sure, take `{native-pkg-name}`. -// REMOVE WHEN: the old arcadedb-embedded* shims are retired and two releases have shipped with the two-package layout allow-old-name -The scripts on this page ran against the JVM build, version 26.10.2.post1 (formerly `arcadedb-embedded`). The output shown is what it printed. The code is the same for both packages. The wording of an error message can differ on `{native-pkg-name}`. +The scripts on this page ran on Python 3.12 against both packages, version 26.11.1.post2, and both printed the output shown. The code is the same for both packages. == Embedded mode