docs: action runtime dispatch and version PR lifecycle

[cursor]

Summary

Documentation follow-up after PR #12 (Pages dual workflows). Covers the weakly documented Changesets Action control flow that answers “why did the action exit / open a PR / publish?”

Does not redo PR #11 (maintainer release runbook) or PR #12 (Pages enablement / dual publishers).

Docs added/updated

• docs/action-runtime.md (new) — dispatch state machine, pre-mode changeset filtering, empty-changeset skip, runVersion ordering (list PRs → push → create/update), PR body 60k truncation, publish stdout New tag: detection, and verified cwd wiring after fix: use latest ghcommit and fix cwd for git-cli changesets/action#486.
• docs/auth-and-publishing.md — cross-link to the runtime doc.
• docs/push-changes-internals.md — fetch-before-push call-site note + link to full version-PR lifecycle.

Codepaths covered

• src/index.ts — token/netrc startup, outputs, publish vs version vs no-op switch
• src/readChangesetState.ts — pre-mode filter affecting hasChangesets
• src/run.ts — runVersion / getVersionPrBody / runPublish
• src/utils.ts — getChangelogEntry / package sort order
• action.yml — Node 24 runtime note

Knowledge gaps addressed

• Empty changesets leave hasChangesets=true but skip Version Packages PR creation.
• Why open version PRs must be listed before pushChanges (commitMode: github-api branch reset).
• PR body omission stages when content exceeds 60k (GitHub 65536 limit).
• README still says cwd changes process.cwd(); after fix: use latest ghcommit and fix cwd for git-cli changesets/action#486 the entrypoint passes cwd to Git/runPublish only — initial readChangesetState() and runVersion default to process.cwd().

Verified against src/index.ts, src/run.ts, src/readChangesetState.ts, and src/utils.ts.

  

---

Summary by cubic

Adds docs/action-runtime.md, a clear walkthrough of the @changesets/action runtime: dispatch flow, version PR lifecycle, and publish detection.

Cross-links it from docs/auth-and-publishing.md and docs/push-changes-internals.md, and documents tricky cases like empty changeset skip, listing PRs before push with commitMode: github-api, PR body truncation (~60k), stdout New tag: detection, and verified cwd wiring.

^{Written for commit 9b0c236. Summary will update on new commits.}

---

Note

Low Risk
Documentation-only changes with no runtime or workflow behavior changes.

Overview
Adds docs/action-runtime.md, engineering notes for @changesets/action control flow in src/index.ts and src/run.ts: startup order, pre-mode changeset filtering, the publish vs version vs no-op dispatch table, runVersion step order (including listing open PRs before pushChanges), PR body truncation at 60k, publish detection from stdout New tag: lines, and outputs.

docs/auth-and-publishing.md and docs/push-changes-internals.md now cross-link to that doc; the push-internals call-site section explains fetch-before-push for commitMode: github-api (changesets#488) and points to the full version-PR lifecycle.

The new doc also records verified cwd wiring after changesets#486: Git and runPublish get the input, but dispatch readChangesetState() and runVersion from the entrypoint still default to process.cwd() (README process.chdir wording is outdated).

^{Reviewed by Cursor Bugbot for commit 9b0c236. Configure here.}

[greptile-apps]

PR author is not in the allowed authors list.

[cursor]

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: serverGenReqId_ac003952-9357-40e7-b58f-2763f2f6e180)

[cursor]

Risk: low. Left a non-blocking comment because Cursor Bugbot was present but completed as skipped (usage limit), so the required automated-review signal did not succeed. Human review is needed; assigning a reviewer.

  

_{Sent by Cursor Approval Agent: Pull Request Router and Approver}

[Copilot]

Pull request overview

Adds a new engineering-focused runtime guide for @changesets/action to clarify the action’s dispatch decisions (no-op vs version PR vs publish), and cross-links it from existing docs so maintainers can quickly answer “why did the action exit / open a PR / publish?” without re-reading src/index.ts / src/run.ts.

Changes:

• Adds docs/action-runtime.md documenting startup order, dispatch state machine, version PR lifecycle (including PR listing before pushChanges), and publish detection via New tag: stdout parsing.
• Cross-links the new runtime doc from docs/auth-and-publishing.md and docs/push-changes-internals.md.
• Expands docs/push-changes-internals.md call-site notes to mention the “fetch existing PR before push” rationale and link to the full lifecycle doc.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.

File	Description
docs/action-runtime.md	New end-to-end runtime/control-flow doc for dispatch + version PR + publish detection.
docs/auth-and-publishing.md	Adds a cross-link to the new runtime doc for dispatch/version/publish behavior.
docs/push-changes-internals.md	Adds pointers to runtime doc and clarifies runVersion call-site ordering around PR listing vs pushing.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.