From e34a8a3d0ea0693493e09075c3b8612d339562d8 Mon Sep 17 00:00:00 2001 From: Fabio Kayser Date: Fri, 23 Oct 2026 09:00:58 +0200 Subject: [PATCH] docs: make release guidance independent of version numbers --- README.md | 10 ++++++---- SECURITY.md | 4 ++-- docs/backend-contract.md | 7 ++++--- docs/builtin-sources.md | 5 +++-- docs/cli.md | 2 +- docs/connectors.md | 11 ++++++----- docs/documentation-handoff.md | 10 ++++++++-- docs/index.md | 9 +++++++-- docs/plugin-example.md | 5 +++-- docs/server.md | 2 +- 10 files changed, 41 insertions(+), 24 deletions(-) diff --git a/README.md b/README.md index a2b97b5..e717b91 100644 --- a/README.md +++ b/README.md @@ -19,9 +19,11 @@ Git submodules, and the development tools below are only needed when working on ### Install with uv (recommended) 1. Install [uv](https://docs.astral.sh/uv/getting-started/installation/). -2. Open the [releases page][releases], choose a version compatible with your solution, and download - the `datam8--py3-none-any.whl` file under **Assets**. For a v2 solution, select a v2 - release, including a prerelease if necessary. +2. Open the [current stable release](https://github.com/oraylis/datam8-cli/releases/latest), + check compatibility with your solution, and download the + `datam8--py3-none-any.whl` file under **Assets**. Use the [release history][releases] + when you need an older compatible version. Choose a prerelease only when deliberately + testing that version. 3. In the directory containing the downloaded wheel, run the following commands. Replace `` with the version in the downloaded filename. @@ -108,7 +110,7 @@ Issues are tracked centrally in the DataM8 repository: ## Key docs -- [Central DataM8 handbook](https://github.com/oraylis/datam8/blob/codex/documentation-v2/docs/index.md) +- [Central DataM8 handbook](https://github.com/oraylis/datam8/blob/main/docs/index.md) - [Backend documentation index](docs/index.md) - [CLI examples and exit/output checks](docs/cli.md) - [Agent skill for model maintenance](skills/datam8-cli/SKILL.md) diff --git a/SECURITY.md b/SECURITY.md index 2aa15bd..0ade5c6 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -4,7 +4,7 @@ Use the central [private vulnerability-report route](https://github.com/oraylis/ or DataM8@Oraylis.de if that route is unavailable. Include component versions, reproduction and impact; keep sensitive data out of public issues. -The current documentation covers v2 beta behavior. A supported-release commitment +The current documentation covers DataM8 v2. A supported-release commitment has not been established by this documentation patch. Do not infer a support or response-time guarantee from an old version table. Follow the -[central reporting guidance](https://github.com/oraylis/datam8/blob/codex/documentation-v2/SECURITY.md). +[central reporting guidance](https://github.com/oraylis/datam8/blob/main/SECURITY.md). diff --git a/docs/backend-contract.md b/docs/backend-contract.md index 4ebfb24..63ccac5 100644 --- a/docs/backend-contract.md +++ b/docs/backend-contract.md @@ -1,8 +1,9 @@ # Backend Contract (Canonical) This document is the canonical HTTP contract between the DataM8 Python backend (`datam8-cli`) and the v2 frontend. -It describes this development checkout and its pinned schema, not every published -beta runtime. See [connector development](connectors.md) for the Python interface. +It describes this checkout and its pinned schema. For an installed release, read +this document at the matching version tag; the app's build manifest identifies its +bundled backend. See [connector development](connectors.md) for the Python interface. ## Startup and readiness @@ -27,7 +28,7 @@ All non-readiness logs are written to stderr. - Implementation note: the CLI currently also accepts an omitted token, which disables authentication. Desktop launchers must always provide a non-empty token. -## Current v2 beta route surface +## Current v2 route surface Solution, Base and Model JSON files are read and written as UTF-8; generated text output and v1 migration output are also written as UTF-8 without a BOM. Before diff --git a/docs/builtin-sources.md b/docs/builtin-sources.md index 37a1b65..a99e324 100644 --- a/docs/builtin-sources.md +++ b/docs/builtin-sources.md @@ -1,7 +1,8 @@ # ODCS and Unity Catalog Builtins -This page describes the current development backend and its pinned schema, not -the recorded desktop beta.6 runtime. The plugins `builtin:OdcsFile` and +This page describes the backend in this checkout and its pinned schema. For an +installed release, read it at the matching version tag and check the app's build +manifest for its bundled backend. The plugins `builtin:OdcsFile` and `builtin:DatabricksUnityCatalog` require no external plugin files in the solution and no additional cloud SDKs. Their short IDs `OdcsFile` and `DatabricksUnityCatalog` are also accepted. diff --git a/docs/cli.md b/docs/cli.md index 0d364f2..fd3e4bd 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -55,5 +55,5 @@ browser development requires compatible frontend URL/auth configuration. See On 2026-10-01, CLI validate and docs generation ran successfully against a disposable archive of sample main `68001a2dcaa0b2931ee341f3527b96266a6e46da` with backend `85683fcaeaf13c4573bee3de9c4668b1ba3ab3b9`. This is CLI evidence, not packaged desktop -or live-source acceptance. See [central compatibility](https://github.com/oraylis/datam8/blob/codex/documentation-v2/docs/compatibility.md) +or live-source acceptance. See [central compatibility](https://github.com/oraylis/datam8/blob/main/docs/compatibility.md) and [handoff](documentation-handoff.md). diff --git a/docs/connectors.md b/docs/connectors.md index 3d280de..9f331fd 100644 --- a/docs/connectors.md +++ b/docs/connectors.md @@ -1,8 +1,9 @@ # Connector Plugins -This reference describes the current development Python backend and its pinned -schema. It does not establish compatibility with the recorded desktop beta.6 -runtime. See [the backend contract](backend-contract.md#source-import-and-refresh) +This reference describes the Python backend in this checkout and its pinned +schema. For an installed release, read it at the matching version tag and check +the app's build manifest for its bundled backend. +See [the backend contract](backend-contract.md#source-import-and-refresh) for HTTP and refresh semantics and [the offline example](plugin-example.md) for a complete runnable connector. @@ -257,6 +258,6 @@ Legacy plugins using only `list_schemas()`, `list_tables()` or methods and `TableMetadata` wrapper. Adding abstract methods alone is insufficient. A dataframe-like object with only `to_dicts()` is not a `TableMetadata` result. -The [frontend consumer notes](https://github.com/oraylis/datam8-frontend/blob/feature/external_refresh/docs/connectors_dev.md) +The [frontend consumer notes](https://github.com/oraylis/datam8-frontend/blob/main/docs/connectors_dev.md) explain how the UI uses these results. User workflows belong in the -[central handbook](https://github.com/oraylis/datam8/blob/codex/documentation-v2/docs/user-guide/sources.md). +[central handbook](https://github.com/oraylis/datam8/blob/main/docs/user-guide/sources.md). diff --git a/docs/documentation-handoff.md b/docs/documentation-handoff.md index 12d6b26..28c87fb 100644 --- a/docs/documentation-handoff.md +++ b/docs/documentation-handoff.md @@ -1,4 +1,10 @@ -# Backend Documentation Handoff +# Historical Backend Documentation Handoff + +This page preserves the original documentation handoff. References to local pages, +feature branches and pending publication below describe that task, not the current +repository status. Maintained handbook links now use `main`; tutorial evidence +keeps its recorded commits. Current installation starts at +[Install the CLI](../README.md#install-the-cli). This is a documentation-only package on the agreed feature branch. No product API, schema JSON, dependency pin or target implementation is changed here. @@ -6,7 +12,7 @@ schema JSON, dependency pin or target implementation is changed here. Run `node --test scripts/check-docs.test.mjs` and `node scripts/check-docs.mjs` with Node 24. CI runs those checks without a frontend or sample checkout. -Read the [central handoff](https://github.com/oraylis/datam8/blob/codex/documentation-v2/docs/handoff.md) for branch/workspace mapping, +Read the [central handoff](https://github.com/oraylis/datam8/blob/main/docs/handoff.md) for branch/workspace mapping, results and manual merge order. The new central and component pages are local until their branches are published. After manual merges, update development links to main; keep tutorial evidence bound to commits. Public user workflows belong in the handbook. diff --git a/docs/index.md b/docs/index.md index 4f2923c..f00b3b1 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,6 +1,11 @@ # Backend Documentation -- [Generator 2.0.1 release notes](releases/2.0.1.md) +Technical references describe this checkout. For an installed release, select the +same document at its version tag. General installation guidance follows stable +releases; exact versions remain in release notes and recorded evidence. + +- [Current stable CLI release](https://github.com/oraylis/datam8-cli/releases/latest) +- [Version-specific release notes](releases/) - [CLI usage and output checks](cli.md) - [Canonical HTTP contract](backend-contract.md) - [Server startup/authentication/CORS](server.md) @@ -11,5 +16,5 @@ - [Test fixtures and commands](../tests/README.md) - [CI and package releases](ci.md) - [Local SQL fixture](../tests/db/README.md) -- [Central user handbook](https://github.com/oraylis/datam8/blob/codex/documentation-v2/docs/user-guide/README.md) +- [Central user handbook](https://github.com/oraylis/datam8/blob/main/docs/user-guide/README.md) - [Documentation handoff](documentation-handoff.md) diff --git a/docs/plugin-example.md b/docs/plugin-example.md index 8b635ea..a8ffe15 100644 --- a/docs/plugin-example.md +++ b/docs/plugin-example.md @@ -1,7 +1,8 @@ # Build an Offline Connector -This example targets the current development backend and its pinned schema, not -the recorded desktop beta.6 runtime. Read [the plugin reference](connectors.md) +This example targets the backend in this checkout and its pinned schema. For an +installed release, use the example and references at its matching version tag. +Read [the plugin reference](connectors.md) for interface details. It needs Python 3.12+ and a prepared backend checkout; follow [installation](../README.md) and [testing setup](../tests/README.md). diff --git a/docs/server.md b/docs/server.md index b3daca4..cda153f 100644 --- a/docs/server.md +++ b/docs/server.md @@ -79,7 +79,7 @@ For source import/refresh endpoints and property ownership, see the Generation is synchronous: -- See [the current route surface](backend-contract.md#current-v2-beta-route-surface) +- See [the current route surface](backend-contract.md#current-v2-route-surface) for the implemented `/model/generate` body and response. ## Error envelope