[CI/Tests] Open a daily PR that moves the OME pin

[pallasathena92]

What this PR does

Adds the Move the OME Pin workflow. Once a day, when OME's main is ahead of ome.ref, it opens one pull request that moves the pin to OME's newest commit and regenerates the API reference from that commit. A maintainer reviews and merges that pull request.

• .github/workflows/move-ome-pin.yml runs daily at 15:17 UTC, ahead of the nightly at 09:23 UTC, and on manual dispatch with a dry_run input. Scheduled runs need NIGHTLY_DOCS_ENABLED, like the nightly. It runs on GitHub-hosted runners and calls no model.
• hack/nightly-docs/move_pin.py decides whether the pin has to move and publishes the pull request.
• The automation README, CONTRIBUTING.md and AGENTS.md describe it, and the pre-commit hook's file pattern covers the new workflow.

The rules it follows:

• One pin move at a time. While any open pull request changes ome.ref, it opens no other and never rewrites that one, so a maintainer can push fixes to its branch.
• The pin only moves forward along OME's main.
• Closing a pin pull request without merging it declines that commit. The next OME commit gets a new one.
• The job that runs OME's Makefile and generator has a read-only token. The publishing job receives one commit SHA and one generated page as data, and validates both.

Why we need it

The nightly documents OME at the commit in ome.ref, and nothing moved the pin automatically. Until someone followed the manual steps in CONTRIBUTING.md, the nightly had nothing new to document. OME's main is already ahead of the pin.

How to test

• python3 -m unittest discover -s hack/nightly-docs -p '*_test.py' runs 17 new tests in move_pin_test.py.
• I ran move_pin.py plan against the real repositories, then publish with DRY_RUN=true in a scratch clone, using the page generated from OME at 0510610. It staged only ome.ref, because the regenerated page is identical to the committed one.
• The workflow can't be dispatched before it is on main. After merging, run gh workflow run move-ome-pin.yml -R ome-projects/ome-docs -f dry_run=true, then once without dry_run.

Checklist

• Every commit is signed off (git commit -s)
• pnpm lint && pnpm check && pnpm test && pnpm build passes locally

Summary by CodeRabbit

• New Features
  • Added a daily check for newer OME commits. When an update is available, it opens a pull request to update the OME pin and regenerate the API reference.
  • Added support for manually triggering the update workflow, including dry runs.
• Documentation
  • Added guidance for reviewing automated updates and moving the OME pin manually, including to a specific commit.

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

🧰 Additional context used

📚 Code guidelines (1)

README.md — configured

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Team

Run ID: 5cd4429d-0da0-4539-9af9-f0683b17cd57

📥 Commits

Reviewing files that changed from the base of the PR and between a836ac0 and 46cea0d.

📒 Files selected for processing (7)

• .github/workflows/move-ome-pin.yml
• .pre-commit-config.yaml
• AGENTS.md
• CONTRIBUTING.md
• hack/nightly-docs/README.md
• hack/nightly-docs/move_pin.py
• hack/nightly-docs/move_pin_test.py

Included review availability: This review used your included allowance. 3 included reviews remain after this review. Your included PR review attempts over the past 7 days set your current allowance at 4 reviews per hour.

---

📝 Walkthrough

Walkthrough

Adds a daily and manually dispatched workflow to update the OME pin. When an update is eligible, the workflow regenerates the API reference and publishes the pin and page through a pull request.

Changes

OME pin update

Layer / File(s)	Summary
Plan and generate .github/workflows/move-ome-pin.yml, hack/nightly-docs/move_pin.py, hack/nightly-docs/move_pin_test.py, .pre-commit-config.yaml, AGENTS.md, hack/nightly-docs/README.md	The workflow supports scheduled and manual runs, checks whether OME main is ahead of the pinned commit, and generates the API reference when an update is needed. The script filters invalid or duplicate pin proposals. Tests cover planning decisions and workflow permissions. The hook and setup documentation include the new workflow.
Validate and publish .github/workflows/move-ome-pin.yml, hack/nightly-docs/move_pin.py, hack/nightly-docs/move_pin_test.py, hack/nightly-docs/README.md, CONTRIBUTING.md	The publishing job passes the generated page and target SHA to the script. The script validates the page and checkout, rechecks the update, and creates or reuses a matching branch before opening a pull request. Dry runs stop before branch or pull request creation. Tests cover publishing behavior; documentation describes automated and manual pin moves.

Priority: ➖ Normal

Estimated code review effort: 4 (Complex) | ~40 minutes

Change: Feature

Sequence Diagram(s)

sequenceDiagram
  participant MoveOMEWorkflow
  participant OMEGitHubAPI
  participant OMECheckout
  participant GitHubActionsArtifact
  participant move_pin.py
  participant GitHubPullRequests
  MoveOMEWorkflow->>OMEGitHubAPI: Read newest OME main commit
  MoveOMEWorkflow->>OMECheckout: Check out target commit and generate API reference
  MoveOMEWorkflow->>GitHubActionsArtifact: Upload generated page
  MoveOMEWorkflow->>move_pin.py: Pass baseline, target, page, and dry_run
  move_pin.py->>OMEGitHubAPI: Recheck pin update decision
  move_pin.py->>GitHubPullRequests: Open pull request when publishing proceeds

Loading

Merge Risk: ⚪ Minimal · up to 46cea

This adds a daily workflow that opens a pull request to move the OME pin and regenerate the API reference. The supplied evidence shows no concrete merge-blocking risk. Manual dry-run and live-run checks are still advisable after merge.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 7.14% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 42 functions across 2 files. (5 skipped: 5…	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: adding a daily workflow that opens a pull request to move the OME pin.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

Full details: Docstring Coverage

Explanation

Docstring coverage is 7.14% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 42 functions across 2 files. (5 skipped: 5 unsupported.)

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Autopilot is currently an internal CodeRabbit preview.

---

_{Comment @coderabbitai help to get the list of available commands.}