## Summary This is the first-ever sync of [Starbase](https://github.com/canonical/starbase)-managed shared build/CI/docs conventions into `craft-platforms`. Since the two repositories share no common git history, this merge required `--allow-unrelated-histories` (approved by the repo maintainer running this sync). Used as a test for [CRAFT-5264](https://warthogs.atlassian.net/browse/CRAFT-5264) ## What changed - **Build system**: `common.mk` overhaul (new `format`/`lint` target lists: `format-tombi`, `format-shfmt`, `format-pre-commit`, `lint-code`, `lint-uv-lockfile`, `lint-actions`, etc.), shared `.pre-commit-config.yaml` hooks (`prettier`, `shfmt`), shared `.editorconfig`/`.gitignore` baselines. - **CI/workflows**: shared `check-renovate.yaml`, `policy.yaml`, `release-publish.yaml` workflows; updated `tics.yaml` reusable workflow. - **Docs tooling**: new Sphinx Stack docs subproject (`docs/_dev`, `docs/Makefile`, `docs/redirects.txt`, `docs/requirements.txt`, vale/pa11y config), a restructured `docs/conf.py` (sitemap, llms.txt, rerediraffe redirects, related links, terminal roles), and Diátaxis landing-page conventions. - **Dependency management**: new `docs-sphinx-stack` dependency group (fully Starbase-owned, scoped to Python >=3.10 since this project supports Python 3.8+), merged `tool.uv.constraint-dependencies`. - **New scaffolding**: `AGENTS.md` (derived from `AGENTS.lib.md`), `CONTRIBUTING.md`, `.github/actionlint.yaml`, `.github/zizmor.yaml`, `.prettierignore`. ## Conflict resolution highlights See the merge commit message and inline PR review comments for full provenance/rationale on every changed file. Notable decisions: - Kept `README.md` from the child repo rather than reverting to Starbase's `<placeholder>` template, since the child's is a fully written, accurate README. - Fixed a real docs-venv/project-venv path collision (`DOCS_VENVDIR`) in `Makefile` and `.readthedocs.yaml`, per an explicit rule in the skill's file-ownership map. - Added `[tool.uv.dependency-groups]` scoping so the new `docs-sphinx-stack` group (needs Python >=3.10) doesn't break dependency resolution for this Python 3.8+ project; dropped an unused, redundant `sphinxext-rediraffe` entry. - As a library repo: removed Starbase's demo `starcraft/` scaffold package, `docs/release-notes/`, `.github/README.md`, and scaffold-only tests. - Pre-PR validation (`make format`, `make lint`, `make test-fast`) all pass; a follow-up fixup commit added missing docs deps (`sphinx-toolbox`, `sphinx-pydantic`, etc.) to `docs/requirements.txt` and new spellcheck wordlist entries discovered during validation. ## Preparation PRs Per the skill's preparation-PR rule, these were split out of this merge PR because they're either pre-existing/unrelated issues the merge happened to surface, or large/mechanical changes better reviewed in isolation from the rest of the Starbase-sync content. ### Merged Both have merged into `main`, and this branch has been rebuilt on top of them (see PR comments for details): - #272 — fixed reusable-workflow-caller permissions broken by the Starbase-sourced `policy.yaml`/`qa.yaml`/`security-scan.yaml` workflows this merge pulls in. - #271 — removed `sphinx_toolbox` (including `sphinx_toolbox.latex`) entirely, which doesn't declare `parallel_read_safe` and fails RTD's `fail_on_warning` build once there are more than 5 doc sources with parallel reads enabled. This superseded the `SPHINX_OPTS ?= ... -j 1` workaround that had been in this branch, which has been dropped. ### Not yet merged Once these land, this branch will be rebuilt again to drop the corresponding content from its own diff: - #275 — upgrades `docs/conf.py` and the docs dependency stack to Starbase's current "Sphinx Stack 2.0" template (new `docs-sphinx-stack` dependency group, `canonical-sphinx~=0.6`, sitemap/redirects/llms.txt config). (Supersedes #274, which was closed.) - #276 — adds `AGENTS.md` (derived from Starbase's `AGENTS.lib.md` template) on its own, since it's a large net-new template-derived file. - #277 — a purely mechanical `tombi format` reformat of `pyproject.toml`, separated out from the substantive dependency changes in this merge. ## Labels Adding `PR: Merge` per the skill's requirement. 🤖 This merge was performed by GitHub Copilot CLI following the `update-starbase` skill. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> [CRAFT-5264]: https://warthogs.atlassian.net/browse/CRAFT-5264?atlOrigin=eyJpIjoiNWRkNTljNzYxNjVmNDY3MDlhMDU5Y2ZhYzA5YTRkZjUiLCJwIjoiZ2l0aHViLWNvbS1KU1cifQ