MagicBeanDev/Hookshot
Archived
Watch
6
0
Fork
You've already forked Hookshot
 0
Code Issues 125 Pull requests 205 Activity

docs: add a searchable Starlight documentation site and player guides #2083

Open
bibigurl-yum wants to merge 11 commits from bibigurl-yum/docs/starlight-preview into main
pull from: bibigurl-yum/docs/starlight-preview
merge into: MagicBeanDev:main
Conversation 8 Commits 11 Files changed 55 +9484
bibigurl-yum commented 2026-11-11 02:01:41 +00:00 (Migrated from github.com)

Hookshot’s setup instructions and troubleshooting answers are spread across the README, technical docs, and issue threads. This adds a searchable Starlight site with short guides that point to the existing references, a compatibility checker, and sourced issue examples.

I DM’d NotRexed directly about this. I’m happy to keep the site up to date using the existing documentation, release notes, and issue responses.

Preview

https://bibigurl-yum.github.io/Hookshot/

  • Preserves the original README logo and the forest-green light/dark theme.
  • Provides short installation, settings, updates/saves, and contribution guides that link to the canonical instructions.
  • Collects 11 historical issue-response examples, with current status left to the linked trackers.
  • Includes a browser-only compatibility checker, antivirus guidance linked to #1003, and a live latest-stable-release badge.
  • Links “Report a bug” to the upstream issue chooser and prominently states that no game files are hosted or distributed.

Publication and maintenance

The explicit list in website/content-sources.mjs imports eight pages: five short player guides, the existing save guide, the README, and CONTRIBUTING.md. Internal notes and development references remain on GitHub. Adding a new Markdown file does not automatically publish it. The manual is generated from the README, not maintained as a second copy.

website/site.config.mjs defaults to https://notrexed.github.io/Hookshot/ and edit links to NotRexed/Hookshot:main. Both generated and handwritten pages use that configuration. npm run build:preview supplies the fork overrides. No upstream hosting configuration or deployment workflow is enabled by merging this PR.

The compatibility calculator remains curated logic, but builds and checks now fail if either the README requirements or project-status section changes without a review. website/compatibility-review.json records the reviewed section hashes; the review procedure and regression tests are included. This detects changes in the checked-out source at build time, not upstream changes in the background.

An Action can build/check documentation changes and deploy after merge if the maintainer adopts the site. Node, Astro/Starlight, their lockfile, and hosting are an explicit maintainer decision; the game build does not depend on them. I’m also happy to maintain the fork-hosted version.

Validation

  • Default upstream build/check: 13 pages, 631 local links/assets, valid local anchors and edit targets, unchanged original logo, and 13 tests passed.
  • Fork preview build/check: 13 pages, 632 local links/assets, with correct fork edit targets and all 13 tests passed.
  • Source guard verified to reject changed requirements and GPU status. The reviewed README sections also matched upstream ceb8745 when checked.
  • git diff --check: passed.
  • The earlier full game-free suite in a local integration with upstream 21fa136 reported 301 passed, 5 failed, 50 skipped; all five failures reproduced on untouched upstream. The subsequent review changes are confined to documentation and website source.

Browser access remains unavailable in the authoring environment. Screenshots and desktop/mobile visual and interaction QA are outstanding; they are not claimed as completed.

CI evidence from the reviewed base

All four red source-regression jobs on the original PR run match upstream main at the PR's base, 21fa136:

Check PR run Upstream main run Matching failure
Ubuntu source checks PR log Main log test_make_game_ngx.py: fixture missing switching; both 345 passed / 1 failed / 10 skipped
Windows part 1 PR log Main log Same switching error; both 167 passed / 1 failed / 10 skipped
Windows part 2 PR log Main log test_pipeline_state_portable.py: deprecated fopen with -Werror; both 163 passed / 1 failed / 14 skipped
actionlint PR log Main log linux-appimage.yml:163:9, ShellCheck SC2012

These are comparisons to the reviewed base, not a claim about the newest main commit. Newer main runs inspected during review were pending or cancelled. Check the latest completed CI before merging. This PR does not alter the failing tests, builder, or workflows.

Hookshot’s setup instructions and troubleshooting answers are spread across the README, technical docs, and issue threads. This adds a searchable Starlight site with short guides that point to the existing references, a compatibility checker, and sourced issue examples. I DM’d NotRexed directly about this. I’m happy to keep the site up to date using the existing documentation, release notes, and issue responses. ## Preview https://bibigurl-yum.github.io/Hookshot/ - Preserves the original README logo and the forest-green light/dark theme. - Provides short installation, settings, updates/saves, and contribution guides that link to the canonical instructions. - Collects 11 historical issue-response examples, with current status left to the linked trackers. - Includes a browser-only compatibility checker, antivirus guidance linked to #1003, and a live latest-stable-release badge. - Links “Report a bug” to the upstream issue chooser and prominently states that no game files are hosted or distributed. ## Publication and maintenance The explicit list in `website/content-sources.mjs` imports eight pages: five short player guides, the existing save guide, the README, and CONTRIBUTING.md. Internal notes and development references remain on GitHub. Adding a new Markdown file does not automatically publish it. The manual is generated from the README, not maintained as a second copy. `website/site.config.mjs` defaults to `https://notrexed.github.io/Hookshot/` and edit links to `NotRexed/Hookshot:main`. Both generated and handwritten pages use that configuration. `npm run build:preview` supplies the fork overrides. No upstream hosting configuration or deployment workflow is enabled by merging this PR. The compatibility calculator remains curated logic, but builds and checks now fail if either the README requirements or project-status section changes without a review. `website/compatibility-review.json` records the reviewed section hashes; the review procedure and regression tests are included. This detects changes in the checked-out source at build time, not upstream changes in the background. An Action can build/check documentation changes and deploy after merge if the maintainer adopts the site. Node, Astro/Starlight, their lockfile, and hosting are an explicit maintainer decision; the game build does not depend on them. I’m also happy to maintain the fork-hosted version. ## Validation - Default upstream build/check: **13 pages, 631 local links/assets**, valid local anchors and edit targets, unchanged original logo, and **13 tests passed**. - Fork preview build/check: **13 pages, 632 local links/assets**, with correct fork edit targets and all 13 tests passed. - Source guard verified to reject changed requirements and GPU status. The reviewed README sections also matched upstream `ceb8745` when checked. - `git diff --check`: passed. - The earlier full game-free suite in a local integration with upstream `21fa136` reported 301 passed, 5 failed, 50 skipped; all five failures reproduced on untouched upstream. The subsequent review changes are confined to documentation and website source. Browser access remains unavailable in the authoring environment. Screenshots and desktop/mobile visual and interaction QA are outstanding; they are not claimed as completed. ## CI evidence from the reviewed base All four red source-regression jobs on the original PR run match upstream `main` at the PR's base, `21fa136`: | Check | PR run | Upstream main run | Matching failure | |---|---|---|---| | Ubuntu source checks | [PR log](https://github.com/NotRexed/Hookshot/actions/runs/42943120905/job/130269401220) | [Main log](https://github.com/NotRexed/Hookshot/actions/runs/42942398373/job/130267814758) | `test_make_game_ngx.py`: fixture missing `switching`; both 345 passed / 1 failed / 10 skipped | | Windows part 1 | [PR log](https://github.com/NotRexed/Hookshot/actions/runs/42943120905/job/130269401144) | [Main log](https://github.com/NotRexed/Hookshot/actions/runs/42942398373/job/130267814820) | Same `switching` error; both 167 passed / 1 failed / 10 skipped | | Windows part 2 | [PR log](https://github.com/NotRexed/Hookshot/actions/runs/42943120905/job/130269401369) | [Main log](https://github.com/NotRexed/Hookshot/actions/runs/42942398373/job/130267814660) | `test_pipeline_state_portable.py`: deprecated `fopen` with `-Werror`; both 163 passed / 1 failed / 14 skipped | | actionlint | [PR log](https://github.com/NotRexed/Hookshot/actions/runs/42943120905/job/130269401131) | [Main log](https://github.com/NotRexed/Hookshot/actions/runs/42942398373/job/130267814805) | `linux-appimage.yml:163:9`, ShellCheck SC2012 | These are comparisons to the reviewed base, not a claim about the newest main commit. Newer main runs inspected during review were pending or cancelled. Check the latest completed CI before merging. This PR does not alter the failing tests, builder, or workflows.
hckrman101 (Migrated from github.com) reviewed 2026-11-11 02:20:40 +00:00
hckrman101 (Migrated from github.com) left a comment

Thanks for this, the guides read well and the claims I spot-checked against main's readme hold up (supported build e0f3ccfa, glibc 2.35, AVX2 for the AppImage, 16 GB RAM / 8 GB VRAM / ~60 GB, 10-45 min build, the 60 FPS cap advice, GPU families). No workflow is added or changed, no game-derived content, and the only external call is the browser fetch of GitHub's public releases API (credentials omitted, with a fallback link). node_modules, dist and the generated content are gitignored. Findings, mostly for NotRexed's call on direction:

  1. Two sources of truth. The seven new docs/*.md pages restate the readme (requirements, update flow, menu, save paths, "report a bug") and link back to it. docs/common-issues.md is a dated snapshot ("checked on 2026-11-10") of closed issues with "Unresolved" labels, and compatibility.mjs hard-codes the readme's requirements as separate logic. Both go stale silently when the readme or an issue changes. The PR says a person should review them when sources change, but nothing enforces it (no test ties them to the readme). I'd keep the guides short and link to the readme sections, or accept that the maintainer takes on keeping them in sync.
  2. The site is wired to the fork, not upstream. astro.config.mjs has site: 'https://bibigurl-yum.github.io', an edit link to bibigurl-yum/Hookshot branch docs/starlight-preview, and the same edit URL is written into the frontmatter of prepare-content.mjs, antivirus.md, compatibility.mdx. Merged as is, every "edit" link points at a fork branch. There is also no deploy workflow, so merging this upstream does not publish anything. Those belong in a follow-up once hosting is decided (the author says they are fine to change it).
  3. Size. website/package-lock.json is 6,751 of the 8,102 added lines, plus a Node toolchain (Astro 7, Starlight) in a repo that is otherwise C/Python. That is a maintenance cost (Dependabot noise, Node version requirement >=22.23.4) that the maintainer should accept explicitly. The lockfile itself is fine to commit.
  4. Build publishes more than the guides. prepare-content.mjs publishes every docs/*.md on the site (all 30+ internal design notes), the readme as a "manual", CONTRIBUTING.md and the pipeline-states README. So the readme exists twice on the site (the manual plus the guides built on it). Probably intended, but worth a conscious yes.
  5. Small accuracy point. common-issues.md says the #1976 answer "suggests RX_VK_FSR_FG=0". On main the readme and development guide describe RX_VK_FSR_FG=1 as the opt-in HUD-moving mode and don't document =0, so please re-check that line against the thread, or drop the variable name.
  6. Test/CI state. The PR's red checks (Python source checks on ubuntu and windows, actionlint) don't touch anything this PR changes (no tests, builder or workflows in the diff). The author reports the same switching fixture failure on main; I didn't verify the ubuntu and actionlint failures against main, so please confirm they match main's latest run before merging. The PR description also says screenshots and browser QA are outstanding.

Not approving: whether Hookshot carries a second docs tree and a Node site is the maintainer's decision, so I'm leaving that to @NotRexed. Nothing here is a bug in the code.

Thanks for this, the guides read well and the claims I spot-checked against main's readme hold up (supported build `e0f3ccfa`, glibc 2.35, AVX2 for the AppImage, 16 GB RAM / 8 GB VRAM / ~60 GB, 10-45 min build, the 60 FPS cap advice, GPU families). No workflow is added or changed, no game-derived content, and the only external call is the browser fetch of GitHub's public releases API (credentials omitted, with a fallback link). `node_modules`, `dist` and the generated content are gitignored. Findings, mostly for NotRexed's call on direction: 1. **Two sources of truth.** The seven new `docs/*.md` pages restate the readme (requirements, update flow, menu, save paths, "report a bug") and link back to it. `docs/common-issues.md` is a dated snapshot ("checked on 2026-11-10") of closed issues with "Unresolved" labels, and `compatibility.mjs` hard-codes the readme's requirements as separate logic. Both go stale silently when the readme or an issue changes. The PR says a person should review them when sources change, but nothing enforces it (no test ties them to the readme). I'd keep the guides short and link to the readme sections, or accept that the maintainer takes on keeping them in sync. 2. **The site is wired to the fork, not upstream.** `astro.config.mjs` has `site: 'https://bibigurl-yum.github.io'`, an edit link to `bibigurl-yum/Hookshot` branch `docs/starlight-preview`, and the same edit URL is written into the frontmatter of `prepare-content.mjs`, `antivirus.md`, `compatibility.mdx`. Merged as is, every "edit" link points at a fork branch. There is also no deploy workflow, so merging this upstream does not publish anything. Those belong in a follow-up once hosting is decided (the author says they are fine to change it). 3. **Size.** `website/package-lock.json` is 6,751 of the 8,102 added lines, plus a Node toolchain (Astro 7, Starlight) in a repo that is otherwise C/Python. That is a maintenance cost (Dependabot noise, Node version requirement `>=22.23.4`) that the maintainer should accept explicitly. The lockfile itself is fine to commit. 4. **Build publishes more than the guides.** `prepare-content.mjs` publishes every `docs/*.md` on the site (all 30+ internal design notes), the readme as a "manual", CONTRIBUTING.md and the pipeline-states README. So the readme exists twice on the site (the manual plus the guides built on it). Probably intended, but worth a conscious yes. 5. **Small accuracy point.** `common-issues.md` says the #1976 answer "suggests `RX_VK_FSR_FG=0`". On main the readme and development guide describe `RX_VK_FSR_FG=1` as the opt-in HUD-moving mode and don't document `=0`, so please re-check that line against the thread, or drop the variable name. 6. **Test/CI state.** The PR's red checks (Python source checks on ubuntu and windows, actionlint) don't touch anything this PR changes (no tests, builder or workflows in the diff). The author reports the same `switching` fixture failure on main; I didn't verify the ubuntu and actionlint failures against main, so please confirm they match main's latest run before merging. The PR description also says screenshots and browser QA are outstanding. Not approving: whether Hookshot carries a second docs tree and a Node site is the maintainer's decision, so I'm leaving that to @NotRexed. Nothing here is a bug in the code.
docs/common-issues.md
@ -0,0 +1,93 @@
# Common issues and answers
hckrman101 (Migrated from github.com) commented 2026-11-11 02:20:40 +00:00

A dated snapshot of issue states. These "unresolved / workaround" statuses will drift, and nothing checks them. Consider linking to the issue labels or tracker instead of restating status.

A dated snapshot of issue states. These "unresolved / workaround" statuses will drift, and nothing checks them. Consider linking to the issue labels or tracker instead of restating status.
website/astro.config.mjs
@ -0,0 +1,50 @@
import { defineConfig } from 'astro/config';
hckrman101 (Migrated from github.com) commented 2026-11-11 02:20:40 +00:00

Fork-specific site (and the editLink below, plus the editUrl in generated and hand-written pages) would all need to change for an upstream-hosted site.

Fork-specific `site` (and the `editLink` below, plus the `editUrl` in generated and hand-written pages) would all need to change for an upstream-hosted site.
bibigurl-yum (Migrated from github.com) reviewed 2026-11-11 02:31:59 +00:00
website/astro.config.mjs
@ -0,0 +1,50 @@
import { defineConfig } from 'astro/config';
bibigurl-yum (Migrated from github.com) commented 2026-11-11 02:31:59 +00:00

Addressed in ce09826. website/site.config.mjs now defaults to the upstream Pages host and NotRexed/Hookshot:main edit URLs. Astro, generated frontmatter, and validation share this configuration; handwritten pages inherit it instead of hard-coding the fork. npm run build:preview provides explicit fork overrides. Both modes were built and checked, including checking that every generated edit URL points to an existing source file. Hosting itself remains a maintainer decision; no deployment is enabled by this PR.

Addressed in ce09826. `website/site.config.mjs` now defaults to the upstream Pages host and `NotRexed/Hookshot:main` edit URLs. Astro, generated frontmatter, and validation share this configuration; handwritten pages inherit it instead of hard-coding the fork. `npm run build:preview` provides explicit fork overrides. Both modes were built and checked, including checking that every generated edit URL points to an existing source file. Hosting itself remains a maintainer decision; no deployment is enabled by this PR.
bibigurl-yum (Migrated from github.com) reviewed 2026-11-11 02:32:01 +00:00
docs/common-issues.md
@ -0,0 +1,93 @@
# Common issues and answers
bibigurl-yum (Migrated from github.com) commented 2026-11-11 02:32:01 +00:00

Addressed in ce09826. Removed the current “Unresolved”, “Open investigation”, and workaround-status labels from the table, entries, and homepage badges. The page now describes the responses as historical examples, keeps the original version/report context, and links directly to trackers for current status and advice. It no longer maintains a separate open/fixed status list.

Addressed in ce09826. Removed the current “Unresolved”, “Open investigation”, and workaround-status labels from the table, entries, and homepage badges. The page now describes the responses as historical examples, keeps the original version/report context, and links directly to trackers for current status and advice. It no longer maintains a separate open/fixed status list.
bibigurl-yum commented 2026-11-11 02:32:03 +00:00 (Migrated from github.com)

Thanks for the detailed review. Updated in ce09826:

  1. Sources of truth: shortened the player guides to link to README sections and the existing save/contribution docs. The compatibility build now stops when either reviewed README source section changes; tests cover requirement and GPU-status drift. Historical issue examples no longer carry current open/fixed status labels.
  2. Hosting: centralized configuration defaults to upstream host and edit URLs. Fork-specific values are explicit preview overrides. Default and preview builds both pass, including edit-target validation.
  3. Toolchain size: kept the lockfile for reproducible installs and documented Node/Astro/Starlight as an optional documentation toolchain with its own maintenance cost. Adoption and hosting remain NotRexed’s decision; the game build is unaffected.
  4. Publication scope: replaced the docs-directory scan with an eight-page allowlist. Internal notes stay on GitHub; removed the extra technical-notes index. The built site now has 13 pages rather than 50.
  5. Frame-generation advice: rechecked the exact #1976 response, which does mention RX_VK_FSR_FG=0. Removed the variable from our summary anyway, retaining the v2.0.14 context and linking to the original response/current tracker.
  6. CI and QA: compared Ubuntu, both Windows shards, and actionlint with upstream at the reviewed base. All four match; direct job links, error details, and totals are in the PR description. Newer main runs inspected were pending/cancelled, so I am not claiming those are verified. Both website build modes and all 13 website tests pass. Browser access is still unavailable here, so screenshots and visual/interaction QA remain outstanding.

The fork preview is being refreshed from this commit. No failing game tests or workflow checks were bypassed.

Thanks for the detailed review. Updated in ce09826: 1. **Sources of truth:** shortened the player guides to link to README sections and the existing save/contribution docs. The compatibility build now stops when either reviewed README source section changes; tests cover requirement and GPU-status drift. Historical issue examples no longer carry current open/fixed status labels. 2. **Hosting:** centralized configuration defaults to upstream host and edit URLs. Fork-specific values are explicit preview overrides. Default and preview builds both pass, including edit-target validation. 3. **Toolchain size:** kept the lockfile for reproducible installs and documented Node/Astro/Starlight as an optional documentation toolchain with its own maintenance cost. Adoption and hosting remain NotRexed’s decision; the game build is unaffected. 4. **Publication scope:** replaced the docs-directory scan with an eight-page allowlist. Internal notes stay on GitHub; removed the extra technical-notes index. The built site now has 13 pages rather than 50. 5. **Frame-generation advice:** rechecked [the exact #1976 response](https://git.magicbean.dev/MagicBeanDev/Hookshot/issues/1976), which does mention `RX_VK_FSR_FG=0`. Removed the variable from our summary anyway, retaining the v2.0.14 context and linking to the original response/current tracker. 6. **CI and QA:** compared Ubuntu, both Windows shards, and actionlint with upstream at the reviewed base. All four match; direct job links, error details, and totals are in the PR description. Newer main runs inspected were pending/cancelled, so I am not claiming those are verified. Both website build modes and all 13 website tests pass. Browser access is still unavailable here, so screenshots and visual/interaction QA remain outstanding. The fork preview is being refreshed from this commit. No failing game tests or workflow checks were bypassed.
bibigurl-yum commented 2026-11-11 21:20:23 +00:00 (Migrated from github.com)

Players can now follow development and look for an existing report without needing to understand GitHub’s issue and pull-request workflow. These additions are included in this PR at 5bb5912.

  • Added Progress & updates, with a development overview, searchable reports, feature requests, proposed changes, releases, and plain-language status explanations. Filters cover status, platform, area and reported version; proposed, merged and released work remain distinct.
  • Added Current version watch, using exact reported-version matches and source-reviewed impact summaries. Reports are evidence of reported problems, not confirmed causes or estimates of how many players are affected. Reviewed summaries expire when their source changes.
  • Added What’s being worked on? → Progress & updates on the homepage and a prominent Search for your problem button in the shared header. The button opens and focuses problem search, with a dedicated mobile header row.
  • Added the public-metadata feed collector, optional refresh server, freshness indicators and maintenance instructions. Raw report bodies, account fields and credentials are excluded from the published feed.
  • Applied the bundled Libertinus font roles for body text, emphasis and headings, retaining the font license and monospace code styling.

The fork preview is published and verified: homepage, progress overview, and problem search. The public HTML and feed match the checked deployment build. The snapshot contains 2,490 items collected at 2026-11-11 21:16 UTC.

Refresh limitation: the browser polls the feed every five minutes, but this GitHub Pages preview currently serves a static snapshot. Public continuous updates require hosting the optional refresh service or scheduling snapshot collection and deployment; neither is activated yet.

Validation: default and fork builds/checks passed (14 pages; 691/692 local links and assets), including anchors, search index, source guards and edit targets. All four website test files passed, covering 28 individual tests. The final deployment build passed again. Rendered desktop/mobile layout, keyboard interaction, light/dark themes and screenshots remain unverified because browser access was unavailable. No game build or runtime experiment was performed.

Players can now follow development and look for an existing report without needing to understand GitHub’s issue and pull-request workflow. These additions are included in this PR at `5bb5912`. - Added **Progress & updates**, with a development overview, searchable reports, feature requests, proposed changes, releases, and plain-language status explanations. Filters cover status, platform, area and reported version; proposed, merged and released work remain distinct. - Added **Current version watch**, using exact reported-version matches and source-reviewed impact summaries. Reports are evidence of reported problems, not confirmed causes or estimates of how many players are affected. Reviewed summaries expire when their source changes. - Added **What’s being worked on? → Progress & updates** on the homepage and a prominent **Search for your problem** button in the shared header. The button opens and focuses problem search, with a dedicated mobile header row. - Added the public-metadata feed collector, optional refresh server, freshness indicators and maintenance instructions. Raw report bodies, account fields and credentials are excluded from the published feed. - Applied the bundled Libertinus font roles for body text, emphasis and headings, retaining the font license and monospace code styling. The fork preview is published and verified: [homepage](https://bibigurl-yum.github.io/Hookshot/), [progress overview](https://bibigurl-yum.github.io/Hookshot/progress/), and [problem search](https://bibigurl-yum.github.io/Hookshot/progress/#problem-search). The public HTML and feed match the checked deployment build. The snapshot contains 2,490 items collected at **2026-11-11 21:16 UTC**. **Refresh limitation:** the browser polls the feed every five minutes, but this GitHub Pages preview currently serves a static snapshot. Public continuous updates require hosting the optional refresh service or scheduling snapshot collection and deployment; neither is activated yet. Validation: default and fork builds/checks passed (14 pages; 691/692 local links and assets), including anchors, search index, source guards and edit targets. All four website test files passed, covering 28 individual tests. The final deployment build passed again. Rendered desktop/mobile layout, keyboard interaction, light/dark themes and screenshots remain unverified because browser access was unavailable. No game build or runtime experiment was performed.
bibigurl-yum commented 2026-11-11 21:35:01 +00:00 (Migrated from github.com)

Current version watch needs fresh GitHub data after the site is published. This PR now includes a scheduled refresh Action to collect a complete snapshot, build/check the documentation, and deploy only the checked website every 15 minutes (minutes 7, 22, 37 and 52), with a manual-run option. Failed collection or validation leaves the last successful deployment online; the page shows the data timestamp. GitHub scheduling can be delayed, so this is periodic updating rather than a real-time guarantee.

Intended upstream adoption after this PR is approved: merge .github/workflows/docs-progress.yml with the documentation into NotRexed/Hookshot:main, select GitHub Actions as the Pages source, allow main in the github-pages environment, and set the Actions repository variable DOCS_PROGRESS_ENABLED=true. Then run Refresh documentation progress manually to verify the first deployment. Outside the preview fork, the workflow uses the repository’s default branch and derives hosting/edit links from that repository. A DOCS_SITE_URL variable supports an alternate hosting origin; /Hookshot/ remains the site base.

The fork preview is explicitly enabled in the workflow; upstream requires this deliberate opt-in. No personal access token is needed: collection uses the job’s token, and only the deployment job gets Pages/OIDC write permissions. There is no PR-triggered publishing. Reviewed impact summaries still require human review and expire when their source report changes.

Current status: uploaded in a9de98d on this PR. The workflow-only copy is installed on the fork’s default branch (37a6bdd), Pages now uses GitHub Actions, and the workflow is active. actionlint and the default website build/check passed (14 pages, 693 local links/assets; all four website test files passed). The first manual refresh is queued for a GitHub runner; successful automated deployment has not yet been verified. No upstream hosting settings were changed.

Current version watch needs fresh GitHub data after the site is published. This PR now includes a scheduled refresh Action to collect a complete snapshot, build/check the documentation, and deploy only the checked website every 15 minutes (minutes 7, 22, 37 and 52), with a manual-run option. Failed collection or validation leaves the last successful deployment online; the page shows the data timestamp. GitHub scheduling can be delayed, so this is periodic updating rather than a real-time guarantee. **Intended upstream adoption after this PR is approved:** merge `.github/workflows/docs-progress.yml` with the documentation into `NotRexed/Hookshot:main`, select **GitHub Actions** as the Pages source, allow `main` in the `github-pages` environment, and set the Actions repository variable **`DOCS_PROGRESS_ENABLED=true`**. Then run **Refresh documentation progress** manually to verify the first deployment. Outside the preview fork, the workflow uses the repository’s default branch and derives hosting/edit links from that repository. A `DOCS_SITE_URL` variable supports an alternate hosting origin; `/Hookshot/` remains the site base. The fork preview is explicitly enabled in the workflow; upstream requires this deliberate opt-in. No personal access token is needed: collection uses the job’s token, and only the deployment job gets Pages/OIDC write permissions. There is no PR-triggered publishing. Reviewed impact summaries still require human review and expire when their source report changes. **Current status:** uploaded in `a9de98d` on this PR. The workflow-only copy is installed on the fork’s default branch (`37a6bdd`), Pages now uses GitHub Actions, and the workflow is active. actionlint and the default website build/check passed (14 pages, 693 local links/assets; all four website test files passed). The [first manual refresh](https://github.com/bibigurl-yum/Hookshot/actions/runs/43105456139) is queued for a GitHub runner; successful automated deployment has not yet been verified. No upstream hosting settings were changed.
Joey-Magnus (Migrated from github.com) reviewed 2026-11-11 21:46:42 +00:00
Joey-Magnus (Migrated from github.com) left a comment

On the game-files rule, it's clean. The only images are the existing assets/hookshot.png logo, plus the Libertinus fonts with their OFL licence. There are no game screenshots or game-derived files. The progress server listens on 127.0.0.1 by default, accepts only GET and HEAD, and leaves out report bodies and account fields.

Since the last review, though, the scope has grown well past "docs". It now has a Progress & updates board fed by a collector over 2,490 issues and PRs, an optional refresh server, a "Current version watch" built from curated summaries, and a pending docs-progress.yml that would deploy to Pages every 15 minutes with Pages write permissions. The remaining points are for NotRexed:

  • Does Hookshot carry a Node/Astro toolchain? package-lock.json is 6,751 of the 9,375 lines.
  • Who keeps compatibility-review.json and progress-curation.json current?
  • Does a scheduled job that publishes summaries of open issues belong in the repo?

I'd split it: the short player guides under docs/ with the readme link, which are cheap to review, separately from the site and the progress tracker. The rendered layout is also still unchecked, as the description says.

On the game-files rule, it's clean. The only images are the existing `assets/hookshot.png` logo, plus the Libertinus fonts with their OFL licence. There are no game screenshots or game-derived files. The progress server listens on 127.0.0.1 by default, accepts only GET and HEAD, and leaves out report bodies and account fields. Since the last review, though, the scope has grown well past "docs". It now has a Progress & updates board fed by a collector over 2,490 issues and PRs, an optional refresh server, a "Current version watch" built from curated summaries, and a pending `docs-progress.yml` that would deploy to Pages every 15 minutes with Pages write permissions. The remaining points are for NotRexed: - Does Hookshot carry a Node/Astro toolchain? `package-lock.json` is 6,751 of the 9,375 lines. - Who keeps `compatibility-review.json` and `progress-curation.json` current? - Does a scheduled job that publishes summaries of open issues belong in the repo? I'd split it: the short player guides under `docs/` with the readme link, which are cheap to review, separately from the site and the progress tracker. The rendered layout is also still unchecked, as the description says.
hckrman101 (Migrated from github.com) reviewed 2026-11-11 22:21:04 +00:00
hckrman101 (Migrated from github.com) left a comment

Thanks for the quick rework. Re-reviewed at a9de98d.

Fixed from my first review

  • Sources of truth: the guides are now short and link to readme sections, the issue snapshot no longer restates open/fixed status, and compatibility-review.json plus the build guard fail the build when the readme requirements or status section change. That answers my point 1 well.
  • Fork wiring: site.config.mjs defaults to the upstream host and NotRexed/Hookshot:main edit links, with the fork values only in build:preview.
  • Publication scope: an explicit eight-page allowlist instead of every docs/*.md.
  • The RX_VK_FSR_FG=0 line is gone from the summary.
  • CI is green on this head (Python source checks on both OSes, actionlint, builder, AppImage). Mergeable. The lockfile is still most of the diff, as noted.

Game-files rule (CONTRIBUTING.md): still clean. Images are the existing assets/hookshot.png, fonts are Libertinus with its OFL licence, and there are no game screenshots or game-derived files. The progress feed uses only public issue/PR/release metadata and leaves out bodies and account fields. I agree with Joey-Magnus's review on that.

New since then, and what's still open (all for NotRexed's call)

  1. Scope grew from docs to a progress tracker: a collector over about 2,500 issues and PRs, an optional refresh server, a "Current version watch" with hand-curated summaries (progress-curation.json), and docs-progress.yml. I agree with Joey-Magnus that the player guides under docs/ and the site/tracker are cheap vs. costly to review and would be easier to land separately.
  2. docs-progress.yml is a new scheduled workflow (every 15 minutes) with pages: write and id-token: write on the deploy job. Good points: actions are SHA-pinned, top-level permissions are read-only, no PR trigger, and it is off unless DOCS_PROGRESS_ENABLED=true is set. Still, it burns runner minutes around the clock and publishes summaries of open reports, which the maintainer should accept explicitly. Nit: the workflow hard-codes bibigurl-yum/Hookshot and docs/starlight-preview in three places; if it lands upstream those fork branches should go.
  3. Nothing in CI runs the website tests or build (npm run check), so after merge they only run in that scheduled job. If the site is adopted, a PR-time check for website/** would catch drift sooner.
  4. Maintenance: the toolchain (Node 22.23.4, Astro 7, Starlight), compatibility-review.json and progress-curation.json all need a human when the readme or reports change.
  5. The description still says desktop/mobile rendering, themes and screenshots are unchecked. Please look at it in a browser before merge.

Not approving: whether Hookshot carries a Node docs site and a scheduled publishing job is the maintainer's decision, so I'm leaving that to @NotRexed. I found no code bug in the parts I read.

Thanks for the quick rework. Re-reviewed at `a9de98d`. **Fixed from my first review** - Sources of truth: the guides are now short and link to readme sections, the issue snapshot no longer restates open/fixed status, and `compatibility-review.json` plus the build guard fail the build when the readme requirements or status section change. That answers my point 1 well. - Fork wiring: `site.config.mjs` defaults to the upstream host and `NotRexed/Hookshot:main` edit links, with the fork values only in `build:preview`. - Publication scope: an explicit eight-page allowlist instead of every `docs/*.md`. - The `RX_VK_FSR_FG=0` line is gone from the summary. - CI is green on this head (Python source checks on both OSes, actionlint, builder, AppImage). Mergeable. The lockfile is still most of the diff, as noted. **Game-files rule (CONTRIBUTING.md)**: still clean. Images are the existing `assets/hookshot.png`, fonts are Libertinus with its OFL licence, and there are no game screenshots or game-derived files. The progress feed uses only public issue/PR/release metadata and leaves out bodies and account fields. I agree with Joey-Magnus's review on that. **New since then, and what's still open (all for NotRexed's call)** 1. Scope grew from docs to a progress tracker: a collector over about 2,500 issues and PRs, an optional refresh server, a "Current version watch" with hand-curated summaries (`progress-curation.json`), and `docs-progress.yml`. I agree with Joey-Magnus that the player guides under `docs/` and the site/tracker are cheap vs. costly to review and would be easier to land separately. 2. `docs-progress.yml` is a new scheduled workflow (every 15 minutes) with `pages: write` and `id-token: write` on the deploy job. Good points: actions are SHA-pinned, top-level permissions are read-only, no PR trigger, and it is off unless `DOCS_PROGRESS_ENABLED=true` is set. Still, it burns runner minutes around the clock and publishes summaries of open reports, which the maintainer should accept explicitly. Nit: the workflow hard-codes `bibigurl-yum/Hookshot` and `docs/starlight-preview` in three places; if it lands upstream those fork branches should go. 3. Nothing in CI runs the website tests or build (`npm run check`), so after merge they only run in that scheduled job. If the site is adopted, a PR-time check for `website/**` would catch drift sooner. 4. Maintenance: the toolchain (Node 22.23.4, Astro 7, Starlight), `compatibility-review.json` and `progress-curation.json` all need a human when the readme or reports change. 5. The description still says desktop/mobile rendering, themes and screenshots are unchecked. Please look at it in a browser before merge. Not approving: whether Hookshot carries a Node docs site and a scheduled publishing job is the maintainer's decision, so I'm leaving that to @NotRexed. I found no code bug in the parts I read.
Commenting is not possible because the repository is archived.
Reviewers
No reviewers
Labels
Clear labels   
accessibility
Barrier affecting people with disabilities

  
autorelease: pending

   
autorelease: tagged

   
bug
Something isn't working

  
dependencies
Pull requests that update a dependency file

  
documentation
Improvements or additions to documentation

  
duplicate
This issue or pull request already exists

  
enhancement
New feature or request

  
github_actions
Pull requests that update GitHub Actions code

  
good first issue
Good for newcomers

  
help wanted
Extra attention is needed

  
invalid
This doesn't seem right

  
question
Further information is requested

  
testing wanted

   
wontfix
This will not be worked on

No labels
accessibility
autorelease: pending
autorelease: tagged
bug
dependencies
documentation
duplicate
enhancement
github_actions
good first issue
help wanted
invalid
question
testing wanted
wontfix
Milestone
Clear milestone
No items
No milestone
Assignees
Clear assignees
No assignees
1 participant
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
MagicBeanDev/Hookshot!2083
No description provided.