Version maintenance — check & report (human review, no bot)
Summary
We do not keep a hand-written version list (e.g. versions.toml). Such a file goes stale the moment someone forgets to update it, and every reader sees outdated numbers. We learned this the hard way: a committed versions.toml once listed Nix 2.34.8 while the real latest stable was 2.34.0.
Instead, the lockfiles are the source of truth, and a small script compares them against what is published. Contributors only look and report; maintainers do the bump + test + merge.
Where versions actually live
| Concern |
File |
Controlled by |
| Every npm dependency |
bun.lock |
resolved by bun; bun update refreshes |
| Declared ranges |
package.json (root + apps/* + packages/*) |
hand-edited |
| devenv CLI |
devenv.yaml (ref=v2.1.2) |
bump ref, then devenv update |
| nixpkgs tools (bun, node, oxlint, oxfmt, wrangler…) |
flake.lock (nixpkgs commit) |
nix flake update |
| Nix daemon |
installed separately |
not tracked in repo |
Contributor role (minimal — this is all we ask)
- Run
just check-versions (or bun scripts/check-versions.mjs).
It reads bun.lock, compares every direct dependency against the latest npm version, and prints what is outdated (marked DIRECT).
- For each outdated
DIRECT dependency — or any non-npm package with a newer release (see below) — open an issue saying:
- which package,
- the latest version you saw,
- the link you checked it at.
- That's it. You do not install, build, or test anything.
Maintainers handle: bumping the version, syncing bun.lock / flake.lock, running the test suite, and merging. If the bump breaks something, we deal with it — not you.
Package list (version-less, never goes stale)
The full list — exact npm identifiers, official links, and Windows / macOS / Linux check commands — lives in the docs (we deliberately keep it out of the repo's version-bearing text):
Those docs never contain a version number, so they stay correct. To see the latest version of any entry, run the command in its row (for npm: bunx npm view <npm-name> version).
Non-npm packages
The script does not check these. Check them by hand:
npm hygiene
The npm package name is not always the tool name. Always use the exact identifier from the docs:
rsbuild CLI → @rsbuild/core- oRPC →
@orpc/server
- Drizzle ORM →
drizzle-orm
- TanStack Start →
@tanstack/react-start
Maintainer role
On a report (issue or one-line PR):
- Verify the new version on the link.
- Bump the pin:
package.json / devenv.yaml / flake.lock as needed.
- Sync
bun.lock (bun update) and run the tests.
- Merge.
Good first issue
"Report an outdated dependency (no code required)" is listed in CONTRIBUTING.md and CONTRIBUTING.zh.md.
版本維護 — 檢查與回報（人工審查，不用機器人）
摘要
我們不維護手寫的版本清單（例如 versions.toml）。那種清單只要有人忘記更新就會過時，所有讀到的人看到的都是舊數字。我們吃過虧：versions.toml 曾經寫 Nix 2.34.8，但真正的最新穩定版是 2.34.0。
所以，鎖定檔才是版本真相來源，並用一個小腳本對照發佈版本。貢獻者只需看一眼並回報；維護者負責升級、測試、合併。
版本實際存在哪裡
| 項目 |
檔案 |
如何控管 |
| 每個 npm 依賴 |
bun.lock |
由 bun 解析；bun update 刷新 |
| 宣告的版本範圍 |
package.json（root + apps/* + packages/*） |
手動編輯 |
| devenv CLI |
devenv.yaml（ref=v2.1.2） |
改 ref，再 devenv update |
| nixpkgs 工具（bun、node、oxlint、oxfmt、wrangler…） |
flake.lock（nixpkgs commit） |
nix flake update |
| Nix daemon |
單獨安裝 |
不在 repo 內追蹤 |
貢獻者角色（很輕鬆，就這樣）
- 執行
just check-versions（或 bun scripts/check-versions.mjs）。
它讀取 bun.lock，把每個直接依賴對照 npm 最新版本，並印出過時項目（標記 DIRECT）。
- 對每個過時的
DIRECT 依賴——或任何有更新釋出的非 npm 套件（見下）——開一個 issue，說明：
- 就這樣。你不需要安裝、建置或測試任何東西。
維護者負責：升級版本、同步 bun.lock / flake.lock、跑測試、合併。如果升級壞了，我們處理，不是你。
套件清單（不含版本，永不過時）
完整清單——精確的 npm 識別名、官方連結、Windows / macOS / Linux 查詢指令——放在文件裡（我們刻意不把它寫進 repo 會帶版本號的文字）：
這些文件永遠不含版本號，所以永遠正確。要看任一條目的最新版本，執行該列的命令（npm：bunx npm view <npm-name> version）。
非 npm 套件
腳本不檢查這些，請手動檢查：
npm 衛生
npm 的套件名不一定等於工具名。永遠使用文件裡的精確識別名：
rsbuild CLI → @rsbuild/core- oRPC →
@orpc/server
- Drizzle ORM →
drizzle-orm
- TanStack Start →
@tanstack/react-start
維護者角色
收到回報（issue 或一行 PR）時：
- 在連結上確認新版本。
- 升級對應的 pin：
package.json / devenv.yaml / flake.lock。
- 同步
bun.lock（bun update）並跑測試。
- 合併。
Good first issue
「回報過時的依賴（不需要寫程式）」已列在 CONTRIBUTING.md 與 CONTRIBUTING.zh.md。
Version maintenance — check & report (human review, no bot)
Summary
We do not keep a hand-written version list (e.g.
versions.toml). Such a file goes stale the moment someone forgets to update it, and every reader sees outdated numbers. We learned this the hard way: a committedversions.tomlonce listed Nix2.34.8while the real latest stable was2.34.0.Instead, the lockfiles are the source of truth, and a small script compares them against what is published. Contributors only look and report; maintainers do the bump + test + merge.
Where versions actually live
bun.lockbun updaterefreshespackage.json(root +apps/*+packages/*)devenv.yaml(ref=v2.1.2)devenv updateflake.lock(nixpkgs commit)nix flake updateContributor role (minimal — this is all we ask)
just check-versions(orbun scripts/check-versions.mjs).It reads
bun.lock, compares every direct dependency against the latest npm version, and prints what is outdated (markedDIRECT).DIRECTdependency — or any non-npm package with a newer release (see below) — open an issue saying:Package list (version-less, never goes stale)
The full list — exact npm identifiers, official links, and Windows / macOS / Linux check commands — lives in the docs (we deliberately keep it out of the repo's version-bearing text):
Those docs never contain a version number, so they stay correct. To see the latest version of any entry, run the command in its row (for npm:
bunx npm view <npm-name> version).Non-npm packages
The script does not check these. Check them by hand:
nvm ls-remote | tail/nix eval nixpkgs#nodejs_22.versionnvm list availabledevenv --versiondevenv --versionnix --versionnix --versionsecretspec --versionsecretspec --versionjust --versionjust --versionnpm hygiene
The npm package name is not always the tool name. Always use the exact identifier from the docs:
rsbuildCLI →@rsbuild/core@orpc/serverdrizzle-orm@tanstack/react-startMaintainer role
On a report (issue or one-line PR):
package.json/devenv.yaml/flake.lockas needed.bun.lock(bun update) and run the tests.Good first issue
"Report an outdated dependency (no code required)" is listed in CONTRIBUTING.md and CONTRIBUTING.zh.md.
版本維護 — 檢查與回報（人工審查，不用機器人）
摘要
我們不維護手寫的版本清單（例如
versions.toml）。那種清單只要有人忘記更新就會過時，所有讀到的人看到的都是舊數字。我們吃過虧：versions.toml曾經寫 Nix2.34.8，但真正的最新穩定版是2.34.0。所以，鎖定檔才是版本真相來源，並用一個小腳本對照發佈版本。貢獻者只需看一眼並回報；維護者負責升級、測試、合併。
版本實際存在哪裡
bun.lockbun update刷新package.json（root +apps/*+packages/*）devenv.yaml（ref=v2.1.2）devenv updateflake.lock（nixpkgs commit）nix flake update貢獻者角色（很輕鬆，就這樣）
just check-versions（或bun scripts/check-versions.mjs）。它讀取
bun.lock，把每個直接依賴對照 npm 最新版本，並印出過時項目（標記DIRECT）。DIRECT依賴——或任何有更新釋出的非 npm 套件（見下）——開一個 issue，說明：套件清單（不含版本，永不過時）
完整清單——精確的 npm 識別名、官方連結、Windows / macOS / Linux 查詢指令——放在文件裡（我們刻意不把它寫進 repo 會帶版本號的文字）：
這些文件永遠不含版本號，所以永遠正確。要看任一條目的最新版本，執行該列的命令（npm：
bunx npm view <npm-name> version）。非 npm 套件
腳本不檢查這些，請手動檢查：
nvm ls-remote | tail/nix eval nixpkgs#nodejs_22.versionnvm list availabledevenv --versiondevenv --versionnix --versionnix --versionsecretspec --versionsecretspec --versionjust --versionjust --versionnpm 衛生
npm 的套件名不一定等於工具名。永遠使用文件裡的精確識別名：
rsbuildCLI →@rsbuild/core@orpc/serverdrizzle-orm@tanstack/react-start維護者角色
收到回報（issue 或一行 PR）時：
package.json/devenv.yaml/flake.lock。bun.lock（bun update）並跑測試。Good first issue
「回報過時的依賴（不需要寫程式）」已列在 CONTRIBUTING.md 與 CONTRIBUTING.zh.md。