Hallo ubtrace documentation shall descibe howto know the used versions of the tools.

[PhilipPartsch]

Is your feature request related to a problem? Please describe.
We do habe an issue and it is unclear to know which version of the involved tools are used.

Describe the solution you'd like
We need on documentation root a clear description howto know the versions of the involved tools. To review the procedure, I suggest to add this procedure to a regression test and add a review question to the review list.

Describe alternatives you've considered
None

Additional context
Pleade keep in mind, even the webpage of ubtrace shall easily show the tools version and this shall be documented on this page, too.

[patdhlk]

Hi @PhilipPartsch — thanks for raising this, this is a fair traceability ask. Let me lay out the current state honestly so we can scope the fix.

What is shown today

• ubTrace UI version is rendered in the left sidebar footer when the sidebar is expanded. It is sourced from the runtime env var UBTRACE_BUILD_VERSION (set in docker-compose-prod.yml).
• ubt_sphinx version can be queried on the build host via pip show ubt_sphinx (or uv pip show / rye show) — the package is installed from pypi.useblocks.com.
• sphinx-needs / Sphinx versions can be queried the same way (pip show sphinx-needs, pip show sphinx).
• Docker image tag identifies the ubTrace build on the server: docker inspect <container> --format '{{.Config.Image}}' returns e.g. .../useblocks/ub-backend:1.4.0 (and image tags also include a sha-<commit> variant per build).

What is not shown today (gaps)

1. The ubt_sphinx builder writes a needs.json whose creator field already carries {program: "sphinx_needs", version: "8.0.0"}. Today the ingest preprocessor drops that — only format_version is propagated into the NDJSON header that the backend persists. So the toolchain version that produced a given imported version is not stored or surfaced in the UI.
2. There is no "About" / "Versions" panel in the webpage that lists tool versions side-by-side.
3. There is no doc page that explains, end-to-end, "how do I find out which versions are in play."

Proposed scope of work

1. Capture in the ingest payload. Extend ubt_sphinx to emit ubt_sphinx_version, sphinx_needs_version, and sphinx_version into the NDJSON header, alongside the existing format_version.
2. Persist in the backend. Add the captured versions to the version/build record so they survive ingest.
3. Show in the UI. Two surfaces:
   • A per-imported-version chip / detail panel showing the toolchain versions that produced that data (answers: "which ubt_sphinx produced this?").
   • A global "About ubTrace" dialog reachable from the sidebar footer, listing the UI build, backend build, and Git commit short SHA.
4. Document on the docs root. New page (e.g. docs/source/usage/versions.rst) with a checklist: how to read the UI footer, how to open the About dialog, how to query ubt_sphinx / sphinx-needs / Sphinx versions on the build host, how to check the container image tag.
5. Regression coverage. Add an E2E assertion that the imported-version detail panel renders the toolchain versions for a known fixture, and a docs CI check that the versions page exists and lists every tool we ship.

One clarifying question — when you say "involved tools", do you also mean the regression-relevant non-Sphinx side (Postgres, Elasticsearch, Keycloak versions baked into the bundle)? Those are different in nature (infra vs. authoring toolchain) and we'd surface them differently (Admin → System Info panel, not the docs version page). Happy either way, just want to confirm scope.