docs: changelog release myths and version-PR pitfalls

[cursor]

Summary

Documentation follow-up after merged PR #14. Corrects inaccurate publish/changelog guidance discovered while verifying getChangelogEntry / createRelease against source, and documents a few version-path pitfalls that were easy to miss.

Does not redo open PR #11 (docs/maintainer-release.md / branch default).

Docs added/updated

• docs/action-runtime.md — getChangelogEntry always returns an object; missing version heading → full changelog body (no throw). Version-path pitfalls: whitespace script.split, empty # Releases, CHANGELOG required on version path, only existingPullRequests.data[0] updated. Stale README cwd note removed.
• docs/troubleshooting.md — replace “missing entry throws” myth; new §5 for version PR / script pitfalls; renumber rate-limit / permissions sections.
• docs/auth-and-publishing.md — cross-link section number update.
• action.yml — createGithubReleases description now matches README (false skips both tags and Releases).

Codepaths covered

• src/utils.ts → getChangelogEntry
• src/run.ts → createRelease, runVersion (script split, PR update, changelog read)
• src/index.ts → publish / version inputs via runPublish / runVersion
• action.yml → createGithubReleases

Knowledge gaps addressed

• Docs claimed a missing changelog entry throws on Release creation; the helper never returns falsy, so Releases can ship with the entire changelog as the body.
• Version path vs publish path CHANGELOG ENOENT asymmetry was under-documented.
• Custom version/publish are not shell-invoked; only the first open Version Packages PR is updated.
• action.yml still described createGithubReleases as Releases-only after README was fixed in docs: cwd accuracy, pushTag pitfalls, consumer troubleshooting #14.

Verified against src/utils.ts and src/run.ts (including a local getChangelogEntry missing-heading check).

  

---

Summary by cubic

Clarifies release/version behavior in docs and aligns action.yml for createGithubReleases. Fixes incorrect guidance on changelog parsing and documents version-PR pitfalls to prevent confusion.

• Bug Fixes
  • Documented that getChangelogEntry always returns { content, highestLevel }; missing version heading falls back to the full changelog.
  • Clarified version vs publish paths: version path throws on missing CHANGELOG.md; publish path skips ENOENT.
  • Noted script handling: custom version/publish are split by whitespace only (no shell), and only the first open Version Packages PR is updated.
  • Updated action.yml so createGithubReleases: false skips both tag pushes and GitHub Releases.
  • Renumbered cross-links and removed stale cwd note; affirmed @changesets/cli resolution and root-package tag behavior.

^{Written for commit 7475f21. Summary will update on new commits.}

---

Note

Low Risk
Changes are documentation and action.yml input descriptions only; no runtime code paths are modified.

Overview
Documentation follow-up that aligns docs and action.yml with actual runtime behavior after verifying getChangelogEntry, createRelease, and runVersion in source.

getChangelogEntry / GitHub Releases: Docs no longer claim a missing version heading causes Release creation to throw. The helper always returns { content, highestLevel }; a missing heading can put the entire changelog in the Release body. Troubleshooting now covers that symptom and the version vs publish asymmetry (version path throws on missing CHANGELOG.md; publish skips ENOENT per package).

Version Packages PR pitfalls: action-runtime.md documents whitespace-only script.split for custom version/publish (no shell), empty # Releases when versions don’t change, and that only existingPullRequests.data[0] is updated when duplicate open PRs exist.

createGithubReleases: action.yml description now states false skips both tag pushes and GitHub Release creation, matching README and runPublish (the flag gates pushTag and createRelease together).

Minor doc maintenance: stale cwd README note removed; troubleshooting sections renumbered; cross-links updated.

^{Reviewed by Cursor Bugbot for commit 7475f21. Configure here.}

[semanticdiff-com]

Review changes with  

Changed Files

File	Status
action.yml	0% smaller
docs/action-runtime.md	Unsupported file format
docs/auth-and-publishing.md	Unsupported file format
docs/troubleshooting.md	Unsupported file format

[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_724e633a-1c5b-4c36-83b3-bb5daad31d0e)

[cursor]

Risk: low. Left a non-blocking comment because Cursor Bugbot did not complete successfully (check status: skipping; usage limit reached), so automated review could not clear this PR. Human review is needed; assigning reviewers.

  

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

[Copilot]

Pull request overview

This PR updates documentation and action.yml input text to better match the action’s actual release/version behavior, especially around changelog parsing and Version Packages PR edge cases.

Changes:

• Corrects docs about getChangelogEntry behavior (missing version heading doesn’t throw; can yield full changelog body) and documents version/publish pitfalls (whitespace script.split, CHANGELOG.md requirements, and only updating the first open version PR).
• Renumbers troubleshooting sections and updates cross-links accordingly.
• Updates action.yml to clarify that createGithubReleases: false skips both tag pushes and GitHub Release creation.

Reviewed changes

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

File	Description
docs/troubleshooting.md	Updates troubleshooting guidance for release body/changelog behavior and adds a new section on Version Packages PR/script pitfalls.
docs/auth-and-publishing.md	Adjusts the troubleshooting section reference after renumbering.
docs/action-runtime.md	Expands/clarifies runtime documentation for runVersion, runPublish, and changelog parsing behavior.
action.yml	Aligns createGithubReleases input description with actual behavior (gates both tag pushes and Releases).

---

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