docs(exploration): changelog PR-number resolution robustness (0202) - #190
Closed
crs48 wants to merge 1 commit into
Closed
docs(exploration): changelog PR-number resolution robustness (0202)#190crs48 wants to merge 1 commit into
crs48 wants to merge 1 commit into
Conversation
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Contributor
|
✓ Changelog fragment found — thanks! |
Contributor
|
Preview removed for PR #190. |
Owner
Author
|
Superseded by #191, which folds in this exploration doc plus the implementation (checked off). |
crs48
added a commit
that referenced
this pull request
Jun 18, 2026
## Summary Implements exploration **0202** — makes changelog PR-number resolution **robust and visible** without adding a second commit. (Supersedes the doc-only PR #190, which is folded in here.) The investigation found PR linking *wasn't* actually broken — the deploy-time `resolve-prs.mjs` works — but it was fragile (regex over merge-commit subjects), silent on failure, and entries without screenshots looked bare. This hardens all three. ### Robustness — `resolve-prs.mjs` + deploy - **Authoritative API fallback:** when the git-subject parse misses, resolve via the GitHub `commits/{addSha}/pulls` API (keyed by the fragment's adding commit) — **merge-method-proof**, so rebase-merges resolve too. Verified live: `commits/4f413f61/pulls → #187`. - **Fail-loud:** unresolved fragments now emit a `::warning` annotation + summary line instead of silently shipping numberless. Never blocks the deploy (entries still render). - `deploy-site.yml` passes `GITHUB_TOKEN` to the step. ### Authoring — `new.mjs` - **`--pr auto`** (default) bakes the PR number via `gh pr view` when the branch already has a PR — one commit, visible in the repo/previews/local. Omitted when no PR exists yet → the deploy resolves it. (`--pr <N>` / `--pr none` override.) **This fragment was added that way.** - Fixes the **UTC-tomorrow date drift** (stamps the local day). ### UI — `index.astro` - A **"View PR #N →"** affordance for entries that have a PR but no gallery, so server/docs changes don't read as broken. (Built HTML shows it for #187/#186/#184…) ### Notably *not* done (a finding, not a gap) - The exploration suggested running resolve in the preview workflows. They build only `apps/web`, **not** the Astro `site/`, so the changelog page is never in previews — running resolve there would be dead code. Skipped to avoid useless pipeline surface. ## Testing - `resolve-prs.mjs` resolves all current slug entries via git; API fallback verified live against the real endpoint. - `new.mjs`: local-date + graceful no-PR + bake-on-`--pr` all smoke-tested. - `site/` builds (70 pages); "View PR #187" affordance present in the built changelog HTML. - Not eslint/prettier-gated (lint covers `packages apps`; `format:check` skips `scripts/site`), but formatted and syntax-checked anyway. Exploration: `docs/explorations/0202_..._CHANGELOG_PR_NUMBER_RESOLUTION_ROBUSTNESS.md` (items checked off). 🤖 Generated with [Claude Code](https://claude.com/claude-code)
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Exploration 0202 — Changelog PR-number resolution robustness
Investigates the report that "PR linking broke" — changelog entries showing a title/slug but no PR number, and seeming not to render.
Key finding: PR linking is not actually broken. Verified live: the page renders
pull/187for the OpenRouter entry (and all 33 recent entries have apull/<N>link), and the JSON feed exposes_xnet.pr: 187for every entry.resolve-prs.mjsruns at deploy and resolves correctly.What made it look broken (all real, none a pipeline failure):
prNNN→ title slugs (metered-ai-through-openrouter), so the number is no longer in the id (it's resolved into theprfield at deploy).The legitimate concern: resolution is deploy-only, regex-based (parses merge-commit subjects), silent on failure, and absent from the repo / PR previews / local builds. It works today only because we merge with
gh pr merge(subject carries(#N)).Recommendation (no second commit, minimal added complexity):
resolve-prsauthoritative via the GitHub commits→PRs API (merge-method-proof), git-subject as offline fallback.::warning+ log on any unresolved fragment) instead of silently shipping bare entries.prat authoring time viagh pr view --json number(still one commit) for repo/preview/local visibility.new.mjsUTC-tomorrow date bug.Docs-only exploration — no user-facing change, so
skip-changelog.🤖 Generated with Claude Code