Publication operators

Upgrading the toolkit pin

1.Reasons to change the pin¶

A new defect class lands (D8, ...) → consumers should upgrade so the new check catches it
A post-PDF assertion regresses on a known-good fixture → consumers must upgrade to get the fix
A breaking workflow contract change (CLI rename, dep dropped) → consumers must upgrade in lockstep

Otherwise, leave the pin where it is. A TC in the middle of a publication is better served by a toolkit version that does not change.

2.Upgrade procedure (one consumer)¶

Pick the new SHA. Find the release tag (vX.Y.Z) on OASIS-Docs/publisher-toolkit and resolve it to the commit it marks. Copy the full 40-character commit SHA. Do not pin to the tag name or the branch name, because both can move.
```
git rev-parse 'vX.Y.Z^{commit}'                                        # in a clone with tags fetched
gh api repos/OASIS-Docs/publisher-toolkit/commits/vX.Y.Z --jq '.sha'  # or from the API
```
Toolkit tags are annotated. gh api .../git/refs/tags/vX.Y.Z --jq '.object.sha' and the first line of git ls-remote --tags give the SHA of the tag object, which is not a commit, and verify_consumer_pin.sh rejects it.

Edit one line in each of two workflow files in the consumer's .github/workflows/:

- name: Checkout publisher-toolkit (pinned)
  uses: actions/checkout@v4
  with:
    repository: OASIS-Docs/publisher-toolkit
    token: ${{ secrets.TOOLKIT_READ_TOKEN }}
    ref: <NEW_40_CHAR_SHA>      <-- change this line
    path: toolkit

Both step_1_format_md_and_convert_to_html.yml and step_2_convert_md_to_html_pdf_final.yml need the same SHA.

Commit on a branch and push the branch, not the consumer's main branch.

cd <consumer-tc-clone>
git checkout -b bump-toolkit-pin-vX.Y.Z
# edit the two yml files
git commit -am "Bump publisher-toolkit pin to vX.Y.Z (<short-SHA>)"
git push -u origin bump-toolkit-pin-vX.Y.Z

Run the chain on that branch against a throwaway directory (for example _test/v1.0/draft, holding a small Markdown source committed on the branch) to confirm the new pipeline still produces the same artifacts. The consumer workflows have no dry-run input: step 1 and step 2 commit their output to the branch they run on, so the test output lands on bump-toolkit-pin-vX.Y.Z, not on main. Without --ref, gh workflow run runs the default branch and tests the old pin.
```
gh workflow run step_1_format_md_and_convert_to_html.yml --repo OASIS-Docs/<tc> \
  --ref bump-toolkit-pin-vX.Y.Z \
  -f sync_path=_test/v1.0/draft -f modify_date=YYYY-MM-DD
gh workflow run step_2_convert_md_to_html_pdf_final.yml --repo OASIS-Docs/<tc> \
  --ref bump-toolkit-pin-vX.Y.Z \
  -f sync_path=_test/v1.0/draft -f modify_date=YYYY-MM-DD
```
Verify: HTML linted clean, PDF generated, assert_pdf_quality passed, and step 2 ended with a STEP2 SUCCESS line (toolkit v0.5.0 or later). The workflow run's logs show all three checks passing.
Merge the branch to main once the run passes. Remove the test output the run committed under _test/ before merging, or merge only the two workflow changes.

3.Rollback procedure¶

If a bumped pin breaks a chain run:

cd <consumer-tc-clone>
git log -p .github/workflows/step_1_format_md_and_convert_to_html.yml \
       .github/workflows/step_2_convert_md_to_html_pdf_final.yml \
  | head -50
# Find the prior SHA from the previous commit
git revert HEAD --no-edit
git push

Or, equivalently, edit both ref: lines back to the prior SHA and commit.

The TC repo's spec content is unaffected; only the pinned toolkit version moves.

4.Multi-consumer rollout¶

When a new toolkit version is released, bump the pin in this order:

OASIS-Docs/niemopen
OASIS-Docs/dps
Any other live OASIS-Docs/<tc> consumer

Do not bump all consumers in the same hour. Stagger by at least one chain run so a regression doesn't take down the publishing pipeline for every TC at once.

5.Pin verification¶

After every consumer push that touches a workflow, run:

bash scripts/verify_consumer_pin.sh OASIS-Docs/<tc>

This walks every .github/workflows/*.yml in the consumer, finds every actions/checkout block whose repository: is OASIS-Docs/publisher-toolkit, and asserts:

a ref: line exists in the same with: block
the ref: value is exactly 40 hex characters (no main, no tag name, no branch, no Actions expression, no template placeholder)
the SHA is reachable in OASIS-Docs/publisher-toolkit

Exit codes:

0 PASS: every toolkit checkout pinned to a valid SHA
1 FAIL: at least one checkout is unpinned, points at a branch/tag, or references a SHA not in toolkit history
2 bad usage or missing tooling

The orchestrator verify_toolkit_consumption.sh calls verify_consumer_pin.sh first, then layers on the legacy step_1/step_2 spot-check. Wire verify_consumer_pin.sh OASIS-Docs/<tc> into each consumer's CI as a status check before merge.

6.Worked example: pins on the tag object¶

Until 1 October 2026, both pinned consumers, OASIS-Docs/dps and OASIS-Docs/niemopen, pinned 45c1ad4 in both workflows. That is the SHA of the annotated tag object for v0.3.0, not a commit: the GitHub commits API answers it with "No commit found" (HTTP 422), so scripts/verify_consumer_pin.sh rejects it. The commit the tag marks is d3d599a. On 1 October both repos were re-pinned to d3d599a63ac2693a365a077116f2af6d0c585ee4 in one commit each (dps 241ccf3, niemopen c204740). The toolkit code they run did not change, and the script passes for both.

The same check, run by hand:

git rev-parse 'v0.3.0^{commit}'     # d3d599a63ac2693a365a077116f2af6d0c585ee4
bash scripts/verify_consumer_pin.sh OASIS-Docs/dps
# OK   OASIS-Docs/dps/step_1_format_md_and_convert_to_html.yml pinned to d3d599a...
# OK   OASIS-Docs/dps/step_2_convert_md_to_html_pdf_final.yml pinned to d3d599a...
# PASS OASIS-Docs/dps: all 2 toolkit checkout(s) pinned to valid SHA(s)