docs: netrc overwrite, clean force-push, changelog sort pitfalls

[cursor]

Summary

Documentation follow-up after merged PR #15. Captures additional source-verified pitfalls that were still easy to miss when scanning existing engineering docs.

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

Docs added/updated

• docs/auth-and-publishing.md — $HOME/.netrc is fully rewritten (writeFile) with fixed login github-actions[bot]; multi-host entries are lost for the rest of the job.
• docs/push-changes-internals.md — git-cli always force-pushes after prepareBranch reset; a clean version tree publishes the base SHA and can empty/auto-close the Version Packages PR.
• docs/action-runtime.md — highestLevel walks from file start (can be inflated by newer ### Major Changes sections); preState only surfaced when mode === "pre"; monorepo publish throws on unknown New tag: names and creates Releases via Promise.all.
• docs/troubleshooting.md — symptoms for clean force-push, sort-order pollution, pre-exit, unknown package, and .netrc clobber.

Codepaths covered

• src/index.ts → .netrc writeFile, readChangesetState dispatch
• src/git.ts → prepareBranch + pushChanges clean/dirty force-push
• src/utils.ts → getChangelogEntry / highestLevel
• src/readChangesetState.ts → pre-mode vs exit
• src/run.ts → runPublish monorepo tag match + parallel releases

Knowledge gaps addressed

• Docs implied .netrc was merely “written for auth”; it overwrites the whole file every run.
• push-changes claimed the force-pushed tip is “the commit just created,” which is false when the tree is clean.
• Changelog docs said highestLevel is computed “while walking that slice”; verified against source (and a local newest-first fixture) that newer sections above the target version can inflate sort order.
• Pre-exit and monorepo unknown-package throw paths were under-documented.

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

  

---

Summary by cubic

Clarifies auth and release behavior to prevent surprises: the action overwrites $HOME/.netrc, git-cli can force-push a clean tree and empty the PR, and changelog sorting can be skewed by newer sections; also documents monorepo tag matching and release concurrency.

• Docs updates
  • auth-and-publishing.md — .netrc is fully rewritten with a single github.com machine (login github-actions[bot]); still written with commitMode: github-api; note to recreate multi-host files after the action.
  • action-runtime.md — startup now calls out the .netrc overwrite; preState is only surfaced when mode === "pre"; highestLevel walks from the file start and can inflate sort order; monorepo publish throws on unknown New tag: names and creates releases in parallel.
  • push-changes-internals.md — git-cli always force-pushes; when the tree is clean it pushes the base SHA, which can empty or auto-close the Version Packages PR; comparison table updated.
  • troubleshooting.md — adds symptoms and fixes for unknown package tags, .netrc clobber, clean force-push PR closure, inflated changelog ordering, and pre-exit behavior.

^{Written for commit 72ca139. Summary will update on new commits.}

[semanticdiff-com]

Review changes with  

[greptile-apps]

PR author is not in the allowed authors list.