Maintain the automatic thx mirror¶

Theseus is the source of truth; Jemoka/thx is its public mirror. This guide is private despite the docs/.thx_disclose folder marker because its file policy takes precedence.

What happens after a merge¶

Every push to master, including a merged pull request, starts .github/workflows/thx.yml. The workflow:

1. Tests disclosure rules and exports tracked, disclosed content.
2. Formats exported Python using pinned Ruff with --no-cache.
3. Builds and installs the exported wheel in an isolated environment, imports all public modules, compares job/dataset/evaluation registries with the checked baseline, and exercises the CLI.
4. Generates API reference pages and builds public documentation in strict mode.
5. Exercises real Copybara against a disposable local Git repository, including attribution, exact snapshot copying, no-op syncs, additions, and removals.
6. Uploads the validated snapshot and publishes it to thx/master using the destination-scoped THX_DEPLOY_KEY secret.

Pull requests run validation without publishing. Publishing is restricted to source master; a queued run skips publishing if a newer master revision exists. workflow_dispatch can rerun the pipeline manually on master.

Choose what becomes public¶

See Disclosing Theseus code for file, region, and folder markers. All marker names are case-insensitive. The nearest folder policy wins; file policies override folders, regions override files, and inner regions override outer regions. Private wins any tie at the same scope. Keep this guide's private marker when editing it.

New infrastructure can be released with explicit markers. Scientific experiments, models, datasets, and evaluations must remain within the existing release boundary until intentionally released. To release one, review the code and its dependencies, mark complete imports and definitions, and update tools/disclosure/baseline.json after reviewing the new public registry/module inventory. Never update the baseline merely to silence an unexpected disclosure failure.

Publish a package release¶

The Release workflow is maintained in source .github/workflows/release.yml and explicitly disclosed through Copybara. Its repository guard permits execution only on Jemoka/thx master; the source repository also has this workflow disabled. Edit the source workflow when changing release logic; direct edits to the mirrored workflow are replaced on the next sync.

Run Release from thx Actions, selecting a version bump. Start with dry_run enabled to run the quality gate and build distributions without committing, tagging, or publishing. The normal run prepares the public master snapshot on release, bumps beyond both the release branch and current PyPI version, builds and validates distributions, and publishes to PyPI and GitHub Releases. Copybara updates only master, so release commits and tags are preserved. The PYPI_TOKEN publishing credential belongs to the thx repository.

Verify a release¶

Stage new files before previewing; the exporter ignores untracked files. Use a fresh destination with python3 tools/disclosure/export.py /tmp/thx-preview. Keep builds and import checks in a separate copy so generated files never enter the snapshot. Copybara rejects caches and build/runtime state, including .ruff_cache, .venv, __pycache__, dist, and build.

After publishing, check the source mirror workflow and the destination's CI and Pages workflows. The public site is theseus.jemoka.com. Build API documentation from the filtered checkout: private modules must not have public generated reference pages or links pointing to them. Keep repository links pointing to https://github.com/Jemoka/thx in both checkouts.