Skip to content

Adopt halos-docs-tools and the shared translation gate - #24

Open
mairas wants to merge 2 commits into
mainfrom
feat/shared-translation-workflow
Open

Adopt halos-docs-tools and the shared translation gate#24
mairas wants to merge 2 commits into
mainfrom
feat/shared-translation-workflow

Conversation

@mairas

@mairas mairas commented Aug 13, 2026

Copy link
Copy Markdown
Contributor

The six checkers under scripts/ were copied into four documentation repositories. They now come from halos-org/docs-tools pinned at v0.1.0, and the workflow is the caller stanza for the shared reusable workflow in halos-org/shared-workflows.

The behaviour change is that the run now goes red where the version it replaces always stayed green: it fails when any translation is stale, missing, unstamped or orphaned. It does not yet block a merge — this repository has no branch protection and no ruleset, so the red check sits next to an enabled merge button. Making it required is a separate decision, and it carries a real cost: the gate judges the whole repository, so an English-only edit cannot go green without its translations. See the review synthesis on this PR. It still posts the report as a pull request comment first, so a red run always carries its own explanation.

Verified locally on this branch before pushing: mkdocs build --strict clean, check-anchors site reports all anchors resolving, translation-status --check exits 0 with all nine locales at 8 current pages, and check-glossary, check-typography and map-anchors run against this repository's glossaries under solutions/translation/.

The Italian glossary contrasted this repository's GLOSSARIES dict with the HALPI2 branch, where registering the locale used to be a prerequisite. That dict now lives in the package and carries all nine locales, so the contrast is gone.

The caller deliberately carries no paths filter. A required check that never runs on a pull request touching none of the filtered paths leaves that pull request unmergeable forever.

Same change as hatlabs/halpi2#49. Part of halos-org/halos#147.

The six checkers move out of scripts/ and into the halos-docs-tools
package, pinned at v0.1.0. The workflow shrinks to the caller stanza for
halos-org/shared-workflows, which runs the same commands and, unlike the
advisory version it replaces, fails the run when a translation is stale,
missing, unstamped or orphaned.

One commit rather than a chain: the old workflow invokes the scripts by
path, so deleting them and repointing CI cannot be separated without an
intermediate commit whose CI is broken.

The Italian glossary contrasted this repository's GLOSSARIES dict with
the HALPI2 branch, where registering the locale used to be a
prerequisite. The dict now lives in the package and carries all nine
locales, so the contrast is gone.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@github-actions

Copy link
Copy Markdown

Translation status

da — 8 current
de — 8 current
es — 8 current
fi — 8 current
fr — 8 current
it — 8 current
nb — 8 current
nl — 8 current
sv — 8 current

Every translation of the pages in scope is current.

The documented pre-flight could not reproduce the gate. The Verifying
block ran `translation-status`, which always exits 0; CI runs
`translation-status --check`. A translator following the skill got a
clean local run and a red check -- the same false green this migration
exists to remove.

deploy.yml holds pages: write and id-token: write and ran plain
`uv sync`, while the gate runs `uv sync --locked`. Now that a git
dependency is in the graph, bumping the pin without re-locking made the
two disagree: the gate refuses, the deploy resolves the new ref live and
runs its build backend with the strongest token in the repository.

The obsolete "register your locale in GLOSSARIES" instructions are gone
from the glossaries, so the skill now says where that registration
actually happens: the registries are hardcoded in the package, and a
tenth locale needs an entry in each, a release, and a pin bump.

Also: the caller stanza states what the called workflow enforces; the
Verifying block said four and listed five; and the language-selector
note named two repositories and a count of three where four carry the
block.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@mairas

mairas commented Aug 13, 2026

Copy link
Copy Markdown
Contributor Author

Code review — 7 personas, run against the identical change

This PR applies the same change as hatlabs/halpi2#49, so the review ran there. Full synthesis, all 23 findings: hatlabs/halpi2#49 (comment)

Everything that applied here is fixed and pushed in this branch's fix(docs) commit:

  • The documented pre-flight could not reproduce the gate — the Verifying block ran translation-status, which always exits 0, while CI runs translation-status --check.
  • deploy.yml holds pages: write and id-token: write and ran plain uv sync while the gate runs uv sync --locked. With a git dependency in the graph, a pin bumped without re-locking made the two disagree.
  • Deleting the obsolete "register your locale in GLOSSARIES" instructions removed the only pointer to where registration now happens. The skill says so.
  • The caller stanza now states what the called workflow enforces, since the failing command lives in a repository this one does not contain.
  • Smaller: "All four, every time" over a block of five; the language-selector note naming two repositories and a count of three where four carry the block.

Two decisions are still open and they are not mine to make. Both are in the halpi2 synthesis under findings 1, 3 and 4: the gate judges the whole repository while work happens one page at a time, so an English-only edit cannot go green; and no branch protection or ruleset exists on main here, so a red check does not actually block a merge. Merging today leaves the check advisory, which is the option nobody chose.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant