Repository navigation
docs: detailed English and Chinese docs, and the hook bugs they turned up - #41
Merged
Merged
Conversation
Writing the new docs against vfox 1.0.12 and 1.0.13 turned up these bugs in the hooks. - musl: after the unpack, PostInstall runs `node --version` once and reads the dynamic loader's complaint. The musl builds of 26.8.0 and later need libatomic, which a stock Alpine does not have, so the install used to succeed and the first `node` failed with `Error loading shared library libatomic.so.1`. Now the install stops, nothing is registered, and the message names the package and the command that installs it (`apk add libatomic` on Alpine, `opkg install ...` on OpenWrt). The libstdc++ message names its command too and no longer says the library "is normally installed automatically". Where no command can be run, or node fails for another reason, the install is left alone. - 32-bit ARM Linux: vfox reports `arm` and Node.js names the package `linux-armv7l`. The plugin asked for `linux-arm`, which never existed, so every install on 32-bit ARM ended in "package ... is not listed". - .nvmrc and .node-version under latest_installed and latest_available: releases are matched by their numbers, part by part, and the newest one wins. The text used to be a Lua pattern against vfox's text-sorted list, so `22` picked 22.9.0 over 22.23.3, `22.2` matched 22.23.3, `22.x` matched nothing and a file holding `(` raised `unfinished capture`. `22.x`, `22.x.x` and `22.*` now mean 22, text that is no release number (node, lts/-1, `(`) is returned as it is, and only a leading `v` is dropped, so an `lts/<codename>` with a `v` inside works. `^lts-` is escaped: it matched anything starting with `lt` and turned `lts/-1` into `lts//1`. - PreInstall: `get checksum failed` says why, `HTTP 404 from <url>` or the network error, instead of hiding it. - VFOX_NODEJS_MIRROR may end in several slashes, not only one. The hook tests grow from 28 to 52 cases. The musl check is also covered by running it against Alpine 3.24.1 with and without libstdc++ and libatomic.
Rewrite the README and add a page per topic under docs/: versions and names, platforms, .nvmrc and .node-version, npm and global packages, troubleshooting, development and changes. The pages for the mirror, musl, LTS, building from source and E2E gain the details they lacked. The commands, messages and tables were taken from vfox 1.0.12 and 1.0.13 on Ubuntu 26.04 and Alpine 3.24.1. Pages that quote data give the day it was taken (2026-10-21), and docs/development.md has the commands that refresh it. What exists only on main, and not in 0.5.2, is marked "Unreleased" with the 0.5.2 behaviour next to it and listed in docs/changes.md. docs/development.md also lists the gaps that are still open. docs/e2e.md said the Windows suite keeps a Docker Compose runner; #40 replaced it with tests/e2e/windows/run.ps1.
README_CN.md and docs/zh-CN/ translate the README and every page of docs/ under the same names. Each page, in both languages, starts with a link to the other one, and docs/development.md says how the two are kept in step. Code blocks and quoted messages stay in English, only their comments are translated. A link to another page points at its Chinese heading, and a link to the vfox guides at the zh-hans site. The terms follow vfox-java's Chinese docs.
linghengqian
added
bug
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.
The docs were thin, so this rewrites them after vfox-java's, in English and in Chinese. Writing them meant running every command against vfox 1.0.12 and 1.0.13 in Ubuntu 26.04 and Alpine 3.24.1 containers, which turned up a few bugs in the hooks. Those are fixed here too.
Three commits, so they can be read apart:
fix:the hook bugs, with tests (hooks/,lib/,tests/hooks_test.lua).docs:the English README anddocs/: 7 new pages, the others extended.docs:the Chinese version (README_CN.md,docs/zh-CN/) and the links between the two languages.Bugs fixed
libatomic(official musl builds of 26.8.0 and later)nodethen fails withError loading shared library libatomic.so.1PostInstallrunsnode --versiononce; the install stops and the message givesapk add libatomiclinux-arm, which Node.js never published, so every install failslinux-armv7l(4.0.0 to 23.11.1).nvmrcunderlatest_installed/latest_available22selects 22.9.0 over 22.23.3,22.2matches 22.23.3,22.xselects nothing, a file holding(raisesunfinished capture22.xand22.*mean 22SHASUMS256.txtrequestget checksum failedget checksum failed: HTTP 404 from <url>, or the network errorVFOX_NODEJS_MIRRORending in//The musl check is the one to look at twice. It runs
nodeonce inPostInstall, on musl only, and only an error that the dynamic loader reports (Error loading shared library ...,Error relocating ...) stops the install. Whereio.popenis missing, ornodefails any other way, the install goes on as before.Reviewing
docs/changes.md. After the release,grep -rn -i -e unreleased -e 未发布 docs README*finds the remarks to take out (docs/development.md, "Releasing").docs/development.mdhas the commands that refresh it.docs/e2e.mdsaid the Windows suite keeps a Docker Compose runner; test(e2e): share one tools stage across the Windows images and drop the MSIs #40 replaced it withrun.ps1, so that sentence is corrected.docs/development.md: no ARMv6 package and no 32-bit ARM package from 24 on, nolibatomiccheck on glibc,latest_availabledownloadsindex.jsonat every prompt, and the LTS codename table is hand-made (Node 26 enters LTS on 2026-10-28, its codename is not announced).Tested
Warning) are clean.VFOX_VERSION=latest MIRROR=default: passes. The rest of the matrix, Windows and WSL are left to CI.libstdc++andlibatomic: 22.23.3, 24.22.0 and 25.9.0 install withoutlibatomic; 26.12.0 stops with theapk add libatomicmessage and installs once the package is there.vfox plugin run --os linux --arch armpicksnode-v20.19.5-linux-armv7l.tar.gz, which exists on nodejs.org.