Operator Quickstart

Use this page when you are taking over day-to-day operation of the tooling repository. It is the short operational path; detailed context lives in the linked runbooks.

Tooling Outputs

This repository produces:

  • upstream Science Europe template discovery

  • parser and translation-tree infrastructure

  • metamodel-to-DSW runtime compatibility

  • clean scaffold release assets and preview PDFs

  • demo project fixtures and matching Knowledge Model bundles used by CI

  • helper scripts and workflow templates consumed by the public translated-template repository

Clean scaffold assets are inputs for the public translated-template repository. They are not finished translated templates.

Daily Health Check

Set repository names once before copying GitHub commands:

TOOL_GITHUB_REPO=$(gh repo view --json nameWithOwner --jq .nameWithOwner)
TOOL_OPERATIONS_BRANCH=master
PUBLIC_TEMPLATE_GITHUB_REPO=owner/science-europe-template-zh_Hant
TRANSLATION_OPERATIONS_BRANCH=master

  1. Check the latest tool CI run:

    gh run list \
  --repo "$TOOL_GITHUB_REPO" \
  --workflow headless_render_regression.yml \
  --branch master \
  --limit 3

  2. Confirm these jobs are green:

  3. Confirm clean scaffold releases exist for the currently supported tags:

    gh release list \
  --repo "$TOOL_GITHUB_REPO" \
  --limit 30 \
  --json tagName \
  --jq '.[].tagName | select(startswith("clean-scaffold-dsw-science-europe-"))'

    The release name pattern is:

    clean-scaffold-dsw-science-europe-vX.Y.Z

If these checks pass, the tool repo has a healthy baseline for versions already covered by config/dsw-compat.yml. New upstream tags and public repository sync still need the upgrade and integration flow below.

When Upstream Publishes a New Tag

The scheduled tool workflow automatically scans configured upstream ranges such as v1.29.1+. You do not need to set a tag for the automated path.

When you are manually checking one specific upstream tag, set a local helper variable to keep the commands short:

CHECK_TAG=vX.Y.Z

Tooling side

  1. Wait for the scheduled tool CI, or trigger it manually:

    gh workflow run headless_render_regression.yml \
  --repo "$TOOL_GITHUB_REPO" \
  --ref "$TOOL_OPERATIONS_BRANCH"

  2. Check the latest tool CI run. For a tag whose metamodelVersion is already covered by config/dsw-compat.yml, the run should publish a clean scaffold release. Use CHECK_TAG only for this manual lookup:

    gh release view "clean-scaffold-dsw-science-europe-$CHECK_TAG" \
  --repo "$TOOL_GITHUB_REPO"

  3. If the release exists, the tool repo part is complete for that tag. The release contains the clean upstream scaffold inputs that the public repository can consume.

Public repository sync

If you also operate the public translated-template repository, trigger its sync workflow after the clean scaffold release exists:

gh workflow run document_template_translation_sync.yml \
  --repo "$PUBLIC_TEMPLATE_GITHUB_REPO" \
  --ref "$TRANSLATION_OPERATIONS_BRANCH"

That operations workflow is owned by the public repository. Configure or dispatch it with the exact run id of a reviewed tool-repo master, scheduled, or operator-dispatched run. A write-enabled sync must not select the latest successful run by workflow name because pull-request runs also publish clean scaffold artifacts. The workflow downloads artifacts from the pinned run, updates its own translation-config.yml, creates or refreshes only policy-enabled sync/v* branches, and opens cross-version synchronization PRs according to public repository policy. Review the public repository run there; do not treat the clean scaffold release as a finished translated template.

Important: a green clean scaffold release only means the upstream template can be transformed, packaged, and previewed. It does not mean a translated branch or translated release exists in the public repository.

Use Version Upgrade Runbook for the full upstream tag flow and Public Template Repository Integration for artifact integration details.

When CI Finds an Unsupported Metamodel

  1. Read the discover-upstream-compat summary in the tool CI run.

  2. Check whether CI opened a compatibility probe PR, usually named automation/dsw-compat-probe-*.

  3. Review the probe PR. It copies the closest previous DSW/TDK runtime into a new config/dsw-compat.yml row and reuses that runtime’s pinned KM fixture in config/regression-evidence.yml. CI then tests the API, import, package, complete branch coverage, preview, and PDF paths.

  4. If CI passes, inspect the runtime evidence, clean scaffold artifacts, and preview output before merging. If CI fails, update the DSW/TDK pair, KM assignment, or compatibility code.

  5. Before merging the probe PR, make sure it also ran:

    make sync-dsw-runtime-matrix
make check

Then merge only after human review. A green probe means the tool repo has a tested runtime candidate; it is not an auto-merge signal. Only after that should the public repository record the new scaffold version and decide, through its version_policy, whether to create or refresh a matching sync/v* branch.

When Parser or Translation-Tree Logic Changes

Before asking translators to continue, prove the generated tree is still safe:

make check
make discover-upstream-compat
make build-upstream-artifacts
make generate-compat-ledger

Review the generated compatibility summary at outputs/compat-ledger/dsw-science-europe/summary.md for unexpected cross-version changes in expanded blocks, translation units, placeholders, or missing scaffold packages before handing artifacts to the public repository. Then review the generated regression plan at outputs/compat-ledger/dsw-science-europe/regression-plan.md to see which versions deserve full DSW regression if you need deeper compatibility coverage than the automated plan-recommended matrix run.

Then run a dry-run against the public repository:

TOOL_REPO_DIR=/path/to/document-template-tool
PUBLIC_TEMPLATE_REPO_DIR=/path/to/science-europe-template-zh_Hant
TOOLING_RUN_ID=123456789

make download-clean-scaffold-artifacts \
  TOOL_GITHUB_REPO="$TOOL_GITHUB_REPO" \
  CLEAN_SCAFFOLD_ARTIFACT_RUN_ID="$TOOLING_RUN_ID" \
  CLEAN_SCAFFOLD_ARTIFACT_OUTPUT_DIR=/tmp/clean-scaffolds

make sync-translation-version-branches \
  TRANSLATION_REPO="$PUBLIC_TEMPLATE_REPO_DIR" \
  TRANSLATION_CLEAN_ARTIFACT_ROOT=/tmp/clean-scaffolds \
  TRANSLATION_SYNC_DRY_RUN=true \
  TRANSLATION_SYNC_REFRESH_EXISTING=true

make check-translation-migrations \
  TRANSLATION_REPO="$PUBLIC_TEMPLATE_REPO_DIR" \
  TRANSLATION_CLEAN_ARTIFACT_ROOT=/tmp/clean-scaffolds

This refresh intentionally leaves version-branch workflow files alone. If the workflow template itself changed and you need to update active translation branches, rerun the helper with --sync-workflows using a token with workflow scope. The migration status command should report OK for every source version when there are no exact-source translations waiting to be filled or updated across version branches.

Use Parser and Translation Tree for the full parser-change checklist.

Do Not

  • Do not commit generated outputs/, .cache/, or generated document-template workspaces.

  • Do not edit generated workflow matrix rows by hand; update config/dsw-compat.yml and run make sync-dsw-runtime-matrix.

  • Do not treat clean scaffold releases as translated releases.

  • Do not add public-repository publication tokens to this repo. Translated release and manual import policy belong in the public repository.