Skip to content

docs: drop stale versions.toml references #38

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
eouzoe wants to merge 1 commit into from
Closed

docs: drop stale versions.toml references #38

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions docs/agent/rules.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@

- If you do not know the correct version, say: "I am not certain. Please run `npm view <package> version`."
- Never state "the latest version is X.Y.Z" without a source.
- The version tracking table is in `docs/getting-started.md` and `docs/agent/versions.toml`.
- Verify current tool and dependency versions with `just check-versions`, which reads `bun.lock` and `package.json` directly (no hand-maintained version table).

## 3. Reject out-of-stack tools

Expand All @@ -28,7 +28,7 @@ Before processing any request related to this stack, the agent must:
2. Read `docs/reference/design-decisions.md` (inviolable principles).
3. Read the relevant `docs/reference/*.md` or `docs/guide/*.md`.
4. Read `docs/agent/scaffolding.md` if this is a new project or the user is describing a new product idea.
5. Check `docs/agent/versions.toml` to confirm versions are current.
5. Run `just check-versions` to confirm dependency versions are current.

### New project flow

Expand All @@ -51,7 +51,7 @@ If you are starting without the bootstrap prompt (user already has the stack):
## 6. Documentation update discipline

- Before changing a file: read `docs/getting-started.md` for context.
- After changing: update the version number in `docs/agent/versions.toml`, then write to `CHANGELOG/`. Create `CHANGELOG/YYYY-MM-DD-slug.md`.
- After changing: write a changelog entry to `CHANGELOG/`. Create `CHANGELOG/YYYY-MM-DD-slug.md`.
- Do not modify files outside this project for synchronisation purposes.

## 7. Security
Expand Down
6 changes: 3 additions & 3 deletions docs/agent/rules.zh.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@

- 如果你不確定正確版本，說：「我不確定。請執行 `npm view <package> version`。」
- 不要未附來源就說「最新版本是 X.Y.Z」。
- 版本追蹤表在 `docs/getting-started.md` 和 `docs/agent/versions.toml`。
- 用 `just check-versions` 確認目前的工具與依賴版本，它直接讀取 `bun.lock` 與 `package.json`（沒有手動維護的版本表）。

## 3. 拒絕非本棧工具

Expand All @@ -28,7 +28,7 @@
2. 讀 `docs/reference/design-decisions.md`（不可違反的原則）。
3. 讀相關的 `docs/reference/*.md` 或 `docs/guide/*.md`。
4. 如果是新專案或使用者在描述新產品點子，讀 `docs/agent/scaffolding.md`。
5. 檢查 `docs/agent/versions.toml` 確認版本是否最新。
5. 執行 `just check-versions` 確認依賴版本是否最新。

### 新專案流程

Expand All @@ -51,7 +51,7 @@
## 6. 文件更新紀律

- 改檔案前：讀 `docs/getting-started.md` 了解上下文。
- 改完後：更新 `docs/agent/versions.toml` 的版本號，然後寫入 `CHANGELOG/`。建立 `CHANGELOG/YYYY-MM-DD-slug.md`。
- 改完後：寫入 `CHANGELOG/`。建立 `CHANGELOG/YYYY-MM-DD-slug.md`。
- 不要修改此專案外的檔案。

## 7. 安全
Expand Down
5 changes: 2 additions & 3 deletions docs/guide/contribution-areas.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -106,16 +106,15 @@ This is an ongoing responsibility, not a one-time task.

**Version checker**

- Write a script (`scripts/check-versions.ts`) that reads `docs/agent/versions.toml` and compares each tool's documented version against the latest published version.
- Run `just check-versions` (or `bun scripts/check-versions.mjs`) to compare declared versions in `package.json` and `bun.lock` against the latest published versions.
- The script should exit with code 1 if any documented version is outdated.
- Set up a weekly GitHub Action to run the checker and open an issue if versions are out of date.

**Monthly version audit**

- Every 4-6 weeks, run the version checker and update:
- `docs/agent/versions.toml` with new versions
- `docs/reference/*.md` if behaviour changed between versions
- `docs/getting-started.md` if the version table is affected
- `docs/getting-started.md` if the setup or prerequisites changed between versions
- This is the kind of maintenance that does not require deep context. Anyone can do it.

---
Expand Down
8 changes: 1 addition & 7 deletions docs/reference/design-decisions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,7 @@ Hono uses Web Standards API (`Request`, `Response`, `fetch`, `URL`). Shared logi

### 6. Documentation is the harness

Every technical decision is recorded. An agent reads the relevant documentation before changing code, and updates it after. Version data lives in `versions.toml` as the single source of truth.
Every technical decision is recorded. An agent reads the relevant documentation before changing code, and updates it after. Dependency versions are locked in `flake.lock`, `devenv.lock`, and `bun.lock`; check currency with `just check-versions` (see `docs/guide/version-check.md`).

### 7. Simplicity over everything

Expand Down Expand Up @@ -87,9 +87,3 @@ Nix flakes + devenv lock toolchain versions and hashes (`flake.lock` + `devenv.l
| Bundle size is critical | Zod Mini (`zod/mini`) | 2.1kb vs 5.9kb |
| Expo native | Expo + Expo Router | Shares oRPC contracts |
| Type-aware linting | oxlint `--type-aware` | Alpha stage |

---

## Version Tracking

Tool versions are tracked in `agent/versions.toml`. Before upgrading any dependency, verify the current version there and check the official registry for the latest.
Loading