diff --git a/tests/test_doc_pages.py b/tests/test_doc_pages.py index b442d79d4..ab05252a6 100644 --- a/tests/test_doc_pages.py +++ b/tests/test_doc_pages.py @@ -1741,6 +1741,23 @@ class ArchitectureStatesTheArbitration(unittest.TestCase): self.assertIn(said, section) +class VersionBasisReferenceIsTheSchema(unittest.TestCase): + """profiling.md listed five kinds of version_basis: `unverified`, its + `why` and the `url`, `commit` and `match` keys 18 profiles use were in + the schema alone.""" + + def test_the_row_names_every_kind_reason_and_key(self): + schema = json.loads((ROOT / "schemas" / "emulator.schema.json").read_text(encoding="utf-8")) + basis = schema["$defs"]["version_basis"]["properties"] + page = (WIKI / "profiling.md").read_text(encoding="utf-8") + row = next(line for line in page.splitlines() if line.startswith("| `version_basis` |")) + for word in [*basis["kind"]["enum"], *basis["why"]["enum"], *basis]: + with self.subTest(word=word): + self.assertIn(f"`{word}`", row) + tools = (WIKI / "tools.md").read_text(encoding="utf-8") + self.assertIn("`unverified`", tools) + + class ReportExcerptIsTheRun(unittest.TestCase): """reading-reports.md quoted 'From python scripts/verify.py --platform retrodeck' a run that said 0 required missing after the command had started diff --git a/wiki/profiling.md b/wiki/profiling.md index 0b69e0423..63780e168 100644 --- a/wiki/profiling.md +++ b/wiki/profiling.md @@ -517,7 +517,7 @@ reports the profile as uncheckable, and the CI job that runs | `upstream` | no | original emulator repository URL | | `profiled_date` | see above | date of source analysis. Quote it, or YAML parses it as a date object | | `core_version` | every profile (`tests/test_version_basis.py`) | the version of the code at the pin, read where `version_basis` says. null when the code states none, never `Git`, `SVN` or a branch name. A dict keyed by build mode when the builds differ | -| `version_basis` | every profile (`tests/test_version_basis.py`) | where `core_version` is read: `file` (`path`, `pattern`, optional `format`), `tag` (the nearest `tag` in the pin's history and its `distance`, `core_version` in git describe's form), `alias` (`of`), `package` (`artifact`, the APK or binary read) or `none`. `repo` names `upstream` when the version is the upstream tree's. `profile_sync --verify-version` reads it again, and a pin advance rewrites `core_version` from it | +| `version_basis` | every profile (`tests/test_version_basis.py`) | where `core_version` is read, by `kind`: `file` (`path`, `pattern`, optional `format`, and `url` with its `commit` for a file outside the profile's repositories, such as the package file of a build a platform ships), `tag` (the nearest `tag` in the pin's history and its `distance`, `core_version` in git describe's form, `match` the glob a tag must fit), `alias` (`of`), `package` (`artifact`, the APK or binary read, `url` where it was obtained), `none` (the code states no version: `core_version` null) or `unverified` (no reading could be made: `core_version` stays as written and is reported unconfirmed, `why` says why: `no_pin`, `host_unsupported`, `host_gone`, `host_unreachable`, `pin_off_branch`, `no_artifact`, `no_source`). `repo` names `upstream` or `source_mirror` when the version is that tree's. `profile_sync --verify-version` reads it again, and a pin advance rewrites `core_version` from it | | `source_commit` | see above | commit SHA of `source` the code was read at. Anchors every `source_ref` line number | | `upstream_commit` | no | same, for `upstream` | | `pin_frozen` | no | why `source_commit` is held on purpose rather than followed. The profile is then judged against its own revision, like one pinned to a superseded tag | diff --git a/wiki/tools.md b/wiki/tools.md index 577296f43..3f81d1340 100644 --- a/wiki/tools.md +++ b/wiki/tools.md @@ -591,9 +591,11 @@ shows added, removed and renamed files in the directories the refs point at. says where it is read: a pattern in one file (`file`), the nearest tag and the commits after it (`tag`, written in git describe's form), the profile an alias follows (`alias`), an artefact read outside any source tree -(`package`), or `none` when the code states nothing, with `core_version` -null. `--verify-version` reads it again at the pin and exits 1 on a -difference or a missing basis. `--set-version` writes what the code states. +(`package`), `none` when the code states nothing, with `core_version` +null, or `unverified` when no reading can be made (a forge gone, a host the +tools cannot read, no artefact to read): `core_version` stays as written, +reported unconfirmed, and `why` names the reason. `--verify-version` reads +it again at the pin and exits 1 on a difference or a missing basis. `--set-version` writes what the code states. A pin advance reads the version at the new pin in the same write and is refused when it cannot: a package version moves by hand.