85 lines
3.0 KiB
Markdown
85 lines
3.0 KiB
Markdown
|
# 更新文件 (Update Documentation)
|
|||
|
|
|
|||
|
|
將文件與程式碼庫保持同步，並從「單一事實來源」(source-of-truth) 檔案中自動生成。
|
|||
|
|
|
|||
|
|
## 步驟 1：識別事實來源 (Sources of Truth)
|
|||
|
|
|
|||
|
|
| 來源 | 生成內容 |
|
|||
|
|
|--------|-----------|
|
|||
|
|
| `package.json` 中的腳本 | 可用指令參考 |
|
|||
|
|
| `.env.example` | 環境變數文件 |
|
|||
|
|
| `openapi.yaml` / 路由檔案 | API 端點參考 |
|
|||
|
|
| 原始碼匯出 (Exports) | 公共 API 文件 |
|
|||
|
|
| `Dockerfile` / `docker-compose.yml` | 基礎設施設定文件 |
|
|||
|
|
|
|||
|
|
## 步驟 2：生成腳本參考 (Script Reference)
|
|||
|
|
|
|||
|
|
1. 讀取 `package.json` (或 `Makefile`, `Cargo.toml`, `pyproject.toml`)
|
|||
|
|
2. 擷取所有腳本/指令及其描述
|
|||
|
|
3. 生成參考表格：
|
|||
|
|
|
|||
|
|
```markdown
|
|||
|
|
| 指令 | 描述 |
|
|||
|
|
|---------|-------------|
|
|||
|
|
| `npm run dev` | 啟動具備熱重載功能的開發伺服器 |
|
|||
|
|
| `npm run build` | 進行帶有型別檢查的生產環境建置 |
|
|||
|
|
| `npm test` | 執行帶有覆蓋率報告的測試套件 |
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 步驟 3：生成環境變數文件
|
|||
|
|
|
|||
|
|
1. 讀取 `.env.example` (或 `.env.template`, `.env.sample`)
|
|||
|
|
2. 擷取所有變數及其用途
|
|||
|
|
3. 分類為「必填」與「選填」
|
|||
|
|
4. 記錄預期格式與有效值
|
|||
|
|
|
|||
|
|
```markdown
|
|||
|
|
| 變數 | 是否必填 | 描述 | 範例 |
|
|||
|
|
|----------|----------|-------------|---------|
|
|||
|
|
| `DATABASE_URL` | 是 | PostgreSQL 連接字串 | `postgres://user:pass@host:5432/db` |
|
|||
|
|
| `LOG_LEVEL` | 否 | 日誌詳細程度 (預設：info) | `debug`, `info`, `warn`, `error` |
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 步驟 4：更新貢獻指南 (Contributing Guide)
|
|||
|
|
|
|||
|
|
生成或更新 `docs/CONTRIBUTING.md`，包含：
|
|||
|
|
- 開發環境設定 (先決條件、安裝步驟)
|
|||
|
|
- 可用腳本及其用途
|
|||
|
|
- 測試程序 (如何執行、如何撰寫新測試)
|
|||
|
|
- 程式碼風格強制執行 (Linter, Formatter, Pre-commit hooks)
|
|||
|
|
- PR 提交清單
|
|||
|
|
|
|||
|
|
## 步驟 5：更新維運手冊 (Runbook)
|
|||
|
|
|
|||
|
|
生成或更新 `docs/RUNBOOK.md`，包含：
|
|||
|
|
- 佈署程序 (逐步指引)
|
|||
|
|
- 健康檢查端點與監控
|
|||
|
|
- 常見問題及其解決方案
|
|||
|
|
- 回滾程序 (Rollback)
|
|||
|
|
- 告警與呈報路徑
|
|||
|
|
|
|||
|
|
## 步驟 6：陳舊度檢查 (Staleness Check)
|
|||
|
|
|
|||
|
|
1. 找出超過 90 天未修改的文件檔案
|
|||
|
|
2. 與最近的原始碼變更進行交叉比對
|
|||
|
|
3. 將可能過期的文件標記為需要手動審查
|
|||
|
|
|
|||
|
|
## 步驟 7：顯示摘要
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
文件更新摘要
|
|||
|
|
──────────────────────────────
|
|||
|
|
已更新： docs/CONTRIBUTING.md (腳本表格)
|
|||
|
|
已更新： docs/ENV.md (新增 3 個變數)
|
|||
|
|
標記： docs/DEPLOY.md (已陳舊 142 天)
|
|||
|
|
跳過： docs/API.md (未偵測到變更)
|
|||
|
|
──────────────────────────────
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 規則
|
|||
|
|
|
|||
|
|
- **單一事實來源**：始終從程式碼生成，切勿手動編輯生成的區塊。
|
|||
|
|
- **保留手動區塊**：僅更新生成的區塊；保留手寫的說明文字。
|
|||
|
|
- **標註生成內容**：在生成的區塊前後使用 `<!-- AUTO-GENERATED -->` 標記。
|
|||
|
|
- **不要擅自建立新文件**：除非指令明確要求，否則不要建立新的文件檔案。
|