docs(versioning): identify development docs and distinguish candidate, abandoned and published versions

[yeongseon]

What this PR does

Makes the documentation and the release runbook tell four things apart: development source, a proposed version, an abandoned version and a verified published release.

• Documentation home (English and Korean). docs/index.md and docs/ko/index.md gain an "About this documentation" section:
  • The site is development documentation, rebuilt from main independently of releases. __version__ is not a release: it can name a candidate, or an abandoned version such as 1.11.1.
  • It shows the exact source commit of the build, as a link to tree/<sha>. A small MkDocs hook, scripts/docs_provenance_hook.py, fills in an HTML-comment marker at build time from GITHUB_SHA, or else from git rev-parse HEAD. If neither is available, the page says the commit was not recorded. The hook never contacts GitHub or PyPI.
  • Published releases are on GitHub Releases and in the PyPI history. Their documentation is the docs/ folder at the release tag (example: v1.11.0).
  • Each guide states its tested versions.
• Quick Start (English and Korean). It now says that its 2.1.4 1.11.0 1.13.0 output came from the published PyPI releases it was last run with, on 2026-10-15.
• RELEASING.md:
  • "Which state a version is in" (new). A table of the four states, with the facts that decide each one and a real example: candidate chore(main): release 1.11.2 #910 (1.11.2), abandoned 1.11.1 (chore(main): release 1.11.1 #838) while main read 1.11.1, and published 1.11.0. A failed PyPI or API read makes the state unknown, never "absent" or "newest".
  • §2, bot-updated release PRs (corrected). The runbook said bot-updated PRs "do not start" CI. Observed on chore(main): release 1.11.2 #910's heads on 2026-10-14: GitHub creates the pull_request runs, but they wait as action_required or end failure, both with zero jobs. The section now says so, adds approving the waiting runs as an option besides close/reopen or a push, and adds a table of CI states. The table separates missing, approval-required or not run, running, failed and passed, and says that a success on an older head is stale.
  • §3 lists what the release maintainer records before merging: the classification and user impact checked against the composed CHANGELOG.md (not the bot body), the exact reviewed final head SHA with every required check passed on it, and the review of release-sensitive paths. It adds that a docs-only candidate may wait, that a justified docs-only release is fine, and that commits must never be relabelled to change the version.
  • "§5 After publication" (new):
    1. record completion from the existing tag, Release, publisher run and cookbook report;
    2. review the support and install statements the release changed, keeping each statement's date and evidence and never contacting PyPI from ordinary builds;
    3. follow the ci(release): guard the lifecycle of abandoned-release baseline overrides #945 override rule.

Why

#946. The site deploys from main on every push. At the time of filing, main read 1.11.1, a version that was never published, while PyPI's newest release was 1.11.0. Nothing on the site said which revision a reader was looking at, or that it was not a release. The runbook's description of CI on bot-updated release PRs also did not match what GitHub actually does.

Alternative not chosen

• Multi-version hosting (mike or versioned Pages). The issue rules it out. A link to the tag's docs/ is enough.
• A Material theme override banner on every page. That would replace theme templates. The note goes on the two home pages instead, which are the entry points. The hook can serve any other page that carries the marker.
• Reading PyPI during the build to show the latest published version. The issue rules it out, and a failed lookup would need its own "unknown" state on the site.

Changes

• scripts/docs_provenance_hook.py (new) and mkdocs.yml (hooks:).
• test/test_docs_provenance_hook.py (new, offline, 10 tests). They cover:
  • GITHUB_SHA taking precedence, with case normalized;
  • git as the fallback;
  • an unknown revision (no git, or a failing git) giving None;
  • the English and Korean text with and without a SHA, including the commit link;
  • pages without the marker staying unchanged;
  • both home pages carrying the marker, and mkdocs.yml registering the hook.
• docs/index.md, docs/ko/index.md, docs/QUICKSTART.md, docs/ko/QUICKSTART.md. Their heading, code-block and table structure still match between English and Korean.
• RELEASING.md, docs/llms-full.txt (regenerated) and CHANGELOG.md.

Known differences / Not changed

• No change to runtime code, the current override, version numbers, dependency caps, branch protection, tokens, release PR chore(main): release 1.11.2 #910's state, tags or PyPI.
• RELEASING.md divergence. The runbook is described as kept identical across the sibling repositories. These additions diverge until each sibling adopts them through its own issue; closure here is repository-local.
• Site-build trigger gap. CI's site-build path filter does not include scripts/docs_provenance_hook.py. A PR that changes only the hook is covered by the offline tests, but not by a strict site build. Changing the filter means editing .github/workflows/ci.yml, so it is left for a separate maintainer-reviewed change.
• Not run:
  • the deployed Pages site;
  • a real bot-triggered run, approved or not: the CI-state description rests on the recorded chore(main): release 1.11.2 #910 runs;
  • a PyPI artifact check;
  • any CUBRID run: no example changed, and the Quick Start's existing dated evidence is reused.
• Reviews still needed. The issue asks a documentation maintainer to review the rendered status and a release maintainer to review the checklist. Those are separate from Copilot's review.

Validation

Rendered output. mkdocs build --strict exits 0. The built pages contain the provenance line:

site/index.html:    built from source commit <a href="/cubrid-lab/sqlalchemy-cubrid/tree/767a0bcd72466518f38ef667e1ab51d3eb36eee8"><code>767a0bcd7246
site/ko/index.html: 소스 커밋 <a href="/cubrid-lab/sqlalchemy-cubrid/tree/767a0bcd72466518f38ef667e1ab51d3eb36eee8"><code>767a0bcd7246

That was a local build on base 767a0bc, so the git fallback was used.

Run evidence behind the runbook correction. Read with gh api .../actions/runs?branch=release-please--branches--main--components--sqlalchemy-cubrid: run 38573152583 is action_required with 0 jobs, and run 38573281349 is failure with 0 jobs. Both are pull_request runs by github-actions[bot] on #910's heads. The runs that actually tested #910's final head 2bb1fc7 were started by a maintainer.

Checks:

• pytest -m "not integration" test: 3296 passed, 92 skipped.
• check_docs_translation, check_docs_links, check_agents_docs, lint_changelog and check_support_claims: OK.
• generate_llms_full.py: regenerated.
• ruff check and ruff format --check: clean.

Development route: standalone agent (Claude Code); review route: a submitted GitHub Copilot review, or a maintainer review.

Refs #946

🤖 Generated with Claude Code

[Copilot]

🟡 Changes recommended

Publication visibility is incorrectly presented as completed verification, and the new tests lack required repository-tooling lane registration.

2 open findings

• Register provenance hook tests in REPO_TOOLING_MODULES · New
• Distinguish publication from verification status · New

What changed in this PR

Clarifies development documentation provenance and distinguishes candidate, abandoned, and verified published versions without changing dialect behavior.

Changes:

• Adds source-commit links through a tested MkDocs hook.
• Updates English and Korean entry points with development scope and dated example evidence.
• Expands release-state, CI, and post-publication guidance.

File	Description
test/​test_docs_provenance_hook.py	Tests revision lookup and rendering.
scripts/​docs_provenance_hook.py	Adds build-time source provenance.
RELEASING.md	Clarifies release states and maintainer checks.
mkdocs.yml	Registers the provenance hook.
docs/​QUICKSTART.md	Identifies dated published-package evidence.
docs/​llms-full.txt	Refreshes generated documentation.
docs/​ko/​QUICKSTART.md	Mirrors Quick Start clarification.
docs/​ko/​index.md	Adds Korean development-documentation notice.
docs/​index.md	Adds development scope and release-source links.
CHANGELOG.md	Records documentation and runbook changes.

🧠 Review effort: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

🔵 Needs a closer look

The acceptance criteria still require documentation-maintainer review of rendered pages and release-maintainer review of the operating checklist.

1 open finding

• Register provenance hook tests in REPO_TOOLING_MODULES

1 resolved since last review

• Distinguish publication from verification status

🧠 Review effort: Balanced

[yeongseon]

Documentation and release maintainer review (delegated) of head f87b9cf.

• Docs: the "About this documentation" sections (English and Korean) correctly say the site is development documentation built from main, link the source commit and send readers to published releases and the docs at their tag. The wording that GitHub Releases and PyPI list a release before the cookbook check, and that only "published and verified" proves verification, is accurate. The Quick Start date note matches the published versions it was run with.
• Hook: scripts/docs_provenance_hook.py only reads GITHUB_SHA or git rev-parse HEAD, validates a full 40-hex SHA, and falls back to "not recorded"; it never contacts GitHub or PyPI. Deployed builds run on pushes to main, so the linked commit is a real main commit. 10 offline tests cover it, and it is registered in REPO_TOOLING_MODULES (test/conftest.py, verified at this head; I resolved that thread).
• RELEASING.md: the version-state table (candidate chore(main): release 1.11.2 #910, partial publication, abandoned 1.11.1, published 1.11.0, unknown when facts cannot be read), the corrected bot-candidate CI description and the §5 "After publication" items match this repository's real release state and the publisher's summaries.
• Follow-ups accepted, not blockers: the site-build path filter does not yet include the hook (a separate ci.yml change), and the sibling RELEASING copies adopt this through their own issues.
• Copilot's two rounds are addressed; required checks pass.

Approved for merge.