docs(quantecon): cherry-pick upstream model, batched tags

[mmcky]

Summary

Two related doc / tracker updates so the fork-maintenance docs match how we actually work:

1. Cherry-pick upstream model (commit 5a1d455a)

Updates quantecon/README.md and quantecon/VERSION.yml to reflect two model shifts:

• Feature branches are short-lived. Branch from origin/main, open PR, squash-merge, delete branch. The squash commit on main is the canonical artifact.
• Upstream PRs are prepared by cherry-picking one or more main squash commits onto a fresh upstream/<topic> branch off upstream/main. Lets us bundle related features into a coherent upstream story (e.g. PR Book-style numbering: format, label, section-tagged TOC, auto-prefix #22 + feat(book): section-level scope for proof:* / figure / equation auto-prefix #28 as "book mode + section scope") or split them per upstream maintainer preference.
• Tagging moves from per-PR to batched. qe-vN is cut at a checkpoint covering several merged features, not on each merge.

2. UPSTREAM-PRS.yml tracker (commit 22c057b0)

Adds a new tracked file quantecon/UPSTREAM-PRS.yml for planning how main squash commits bundle into upstream PRs. The two tracker files now have crisp, orthogonal roles (cross-referenced by squash SHA):

File	Question it answers
VERSION.yml	What QuantEcon squash commits are in our main right now? (diagnostic / build identifier)
UPSTREAM-PRS.yml	How do we plan to ship those squash commits upstream? (bundles, dependencies, status)

Seeds UPSTREAM-PRS.yml with three candidates:

• myst-to-ipynb — feat(ipynb): CommonMark ipynb export + image attachment embedding #16, self-contained
• book-mode-with-section-scope — Book-style numbering: format, label, section-tagged TOC, auto-prefix #22 + feat(book): section-level scope for proof:* / figure / equation auto-prefix #28 bundled (feat(book): section-level scope for proof:* / figure / equation auto-prefix #28 builds on Book-style numbering: format, label, section-tagged TOC, auto-prefix #22's auto-prefix hooks; reviewing them together saves upstream a confused pass)
• book-parts — Book parts: section: parts dividers with Roman labels #26, planned (still open against our main)

Also drops the upstream: block from each VERSION.yml merged_features entry (was always pending placeholder, now lives in UPSTREAM-PRS.yml) and adds the missing book-proof-scope (#28) entry there.

Why

• The old "branch from upstream/main, keep alive, push as upstream PR" workflow was awkward when features depended on prior QuantEcon-only features (e.g. feat(book): section-level scope for proof:* / figure / equation auto-prefix #28 building on Book-style numbering: format, label, section-tagged TOC, auto-prefix #22 — couldn't reasonably branch from upstream/main since Book-style numbering: format, label, section-tagged TOC, auto-prefix #22 wasn't there yet).
• Branching from main lets dependencies just work; the squash commit on main is exactly what an upstream PR would show anyway.
• Cherry-picking at upstream-PR time gives per-attempt control over bundling.
• A feature occasionally spans multiple main squash commits (the original PR + a follow-up Copilot-fix PR), and bundles of features sometimes form one upstream story. UPSTREAM-PRS.yml captures both cases naturally; VERSION.yml's flat merged_features could not.

Test plan

• README renders cleanly (preview)
• Diagram aligns
• quantecon/PLAN.md stays gitignored (verified with git check-ignore)
• UPSTREAM-PRS.yml added to .gitignore allow-list

No code changes, no behaviour changes — pure docs / tracker update.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Updates QuantEcon fork-maintenance documentation to reflect a workflow shift toward short-lived feature branches, upstream PR preparation via cherry-picking main squash commits onto upstream/<topic>, and batching qe-vN tags at checkpoints (rather than per merged PR).

Changes:

• Revise branching model documentation (feature branches off origin/main, upstream PR branches off upstream/main via cherry-pick).
• Update upstreaming instructions (new “Opening an upstream PR” section and simplified post-upstream-merge steps).
• Clarify qe-vN tagging as batched checkpoints in both README.md and VERSION.yml.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

File	Description
quantecon/README.md	Updates the maintenance guide to the cherry-pick upstreaming model and batched tagging guidance.
quantecon/VERSION.yml	Updates the header comment to describe checkpoint-based tagging and per-PR feature recording.

Comments suppressed due to low confidence (3)

quantecon/VERSION.yml:15

• "tag may be set later once the next qe-v<N> cuts" is ambiguous/off-by-one (for a newly merged feature, the tag will be set when a new qe-v… tag is cut, i.e. qe-v<N+1> relative to the previous tag). Suggest rephrasing to something like "once the next qe-v tag is cut" or "once qe-v<N+1> is cut" to avoid confusion when following the workflow.

# Per-PR landing only adds the feature to `merged_features` with its squash
# `merge_sha`; `tag` may be set later once the next `qe-v<N>` cuts.

quantecon/README.md:16

• In the "cut a tag" instructions, step 3 says to "Append each newly-included feature to merged_features", but later the README relies on merged_features already containing each feature's merge_sha at upstream-PR time. This reads as two different sources of truth (record features at merge-time vs at tag-time) and could cause duplicated/missing entries. Consider updating step 3 to reflect the intended model (e.g., per-PR: add entry with merge_sha; per-tag: bump qe_version and set/back-fill tag on the already-merged entries).

Tags are cut at meaningful checkpoints, **not per-PR** — typically when a batch of features is ready for downstream dogfooding. To cut a tag:

1. Pick the `main` commit at the head of the batch
2. Tag it: `git tag qe-v<N+1> <sha> -m "qe-v<N+1>: <summary of features included>"` then `git push origin qe-v<N+1>`
3. Append each newly-included feature to `merged_features` in `VERSION.yml` and bump `qe_version`

quantecon/README.md:162

• In this conflict-resolution rebase snippet, origin/main may be stale unless the user has fetched recently. Other snippets in this doc include an explicit git fetch origin first; consider adding it here as well so the instructions reliably rebase onto the latest main.

```bash
git checkout feature/<later>
git rebase origin/main
# resolve conflicts, git add, git rebase --continue
git push --force-with-lease origin feature/<later>

---

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