universal-dev-standards 5.17.0 → 6.0.0

package/bundled/locales/zh-TW/options/code-review/pr-review.md

@@ -0,0 +1,167 @@
+---
+source: options/code-review/pr-review.md
+source_version: 1.0.0
+translation_version: 1.0.0
+status: current
+---
+
+# Pull Request 審查
+
+> **語言**: [English](../../../../options/code-review/pr-review.md) | 繁體中文
+
+**上層標準**: [Code Review Checklist](../../core/code-review-checklist.md)
+
+---
+
+## 概觀
+
+Pull Request（PR）審查是傳統的非同步程式碼審查流程，在合併前先提交變更以供審查。它提供有文件記錄的稽核軌跡，並且很適合分散式團隊。
+
+## 最適用於
+
+- 橫跨不同時區的分散式團隊
+- 非同步工作流程
+- 需要稽核軌跡的專案
+- 開源專案
+- 合規與法規要求
+
+## 工作流程
+
+### 1. 建立 Pull Request
+
+**作者職責：**
+- 撰寫清楚、具描述性的 PR 標題
+- 加入完整的描述
+- 連結相關 issue
+- 指派適當的 reviewer
+- 確保 CI 檢查通過
+
+### 2. 審查
+
+**Reviewer 職責：**
+- 檢查功能與正確性
+- 審查程式碼品質與風格
+- 驗證安全考量
+- 必要時在本機執行測試
+- 提供建設性的回饋
+
+### 3. 回應回饋
+
+**作者職責：**
+- 處理所有回饋意見
+- 以新的 commit 推送修正
+- 回覆評論
+- 準備好後請求重新審查
+
+### 4. Approve 並合併
+
+**最後步驟：**
+- 取得必要的 approval
+- 確保所有檢查通過
+- 使用約定的策略合併
+- 刪除 feature 分支
+
+## 審查檢查清單
+
+### 功能
+
+- [ ] 程式碼是否正常運作？
+- [ ] 是否處理了邊界案例？
+- [ ] 錯誤處理是否適當？
+
+### 程式碼品質
+
+- [ ] 程式碼是否易讀？
+- [ ] 函式是否聚焦（單一職責）？
+- [ ] 是否有程式碼重複？
+- [ ] 命名是否具描述性？
+
+### 安全
+
+- [ ] 是否有 injection 漏洞？
+- [ ] 輸入是否經過驗證？
+- [ ] 是否有憑證外洩？
+- [ ] 相依套件是否安全？
+
+### 測試
+
+- [ ] 是否有足夠的測試？
+- [ ] 測試是否涵蓋邊界案例？
+- [ ] 測試是否易讀且易維護？
+
+## 評論慣例
+
+### 前綴風格
+
+| 前綴 | 意義 | 是否阻擋 |
+|--------|---------|----------|
+| `[REQUIRED]` | 合併前必須修正 | 是 |
+| `[SUGGESTION]` | 考慮修改 | 否 |
+| `[QUESTION]` | 需要釐清 | 否 |
+| `[NIT]` | 細微的風格問題 | 否 |
+| `[PRAISE]` | 做得好 | 否 |
+
+### Emoji 風格
+
+| Emoji | 意義 |
+|-------|---------|
+| ❗ | 阻擋性問題 |
+| ⚠️ | 建議 |
+| 💡 | 想法 |
+| ❓ | 問題 |
+| 👍 | 讚賞 |
+
+## PR 範本
+
+```markdown
+## Summary
+Brief description of changes
+
+## Type of Change
+- [ ] Bug fix
+- [ ] New feature
+- [ ] Breaking change
+- [ ] Documentation update
+
+## Testing
+- [ ] Unit tests added/updated
+- [ ] Manual testing performed
+
+## Checklist
+- [ ] Code follows project style guidelines
+- [ ] Self-review completed
+- [ ] Documentation updated if needed
+```
+
+## 規則
+
+| 規則 | 描述 | 優先級 |
+|------|-------------|----------|
+| 及時審查 | 在 24 小時內審查 | Recommended |
+| 建設性回饋 | 說明原因，而不只是說明內容 | Required |
+| Approve 前先測試 | 確保所有測試通過 | Required |
+| 最少 reviewer 數 | 至少需要一個 approval | Required |
+
+## 與其他方法的比較
+
+| 面向 | PR Review | Pair Programming |
+|--------|-----------|------------------|
+| 時機 | 非同步 | 即時 |
+| 回饋 | 延遲 | 立即 |
+| 知識分享 | 中等 | 高 |
+| 文件記錄 | 較高（PR 評論） | 較低 |
+| 可擴展性 | 高 | 有限 |
+| 遠端友善度 | 容易 | 具挑戰性 |
+
+## 相關選項
+
+- [Pair Programming](./pair-programming.md) - 即時協作審查
+- [Automated Review](./automated-review.md) - 工具輔助審查
+
+---
+
+## 授權
+
+本文件以 [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) 授權釋出。
+
+**來源**: [universal-dev-standards](https://github.com/AsiaOstrich/universal-dev-standards)

package/bundled/locales/zh-TW/options/documentation/api-docs.md

@@ -0,0 +1,191 @@
+---
+source: options/documentation/api-docs.md
+source_version: 1.0.0
+translation_version: 1.0.0
+status: current
+---
+
+# API Documentation
+
+> **語言**: [English](../../../../options/documentation/api-docs.md) | 繁體中文
+
+**Parent Standard**: [Documentation Structure](../../core/documentation-structure.md)
+
+---
+
+## 概觀
+
+API 文件為整合你 API 的開發者提供結構化的參考資料。它涵蓋 endpoint 規格、authentication、request/response 格式以及錯誤處理。
+
+## 最適用於
+
+- REST APIs
+- GraphQL APIs
+- SDK／Library 文件
+- 公開 API
+- 開發者入口網站
+
+## 文件格式
+
+### OpenAPI (Swagger)
+
+| 面向 | 細節 |
+|--------|---------|
+| **Versions** | 3.0、3.1 |
+| **File Types** | `.yaml`、`.json` |
+| **Best For** | REST APIs |
+| **Tools** | Swagger UI、Redoc、Stoplight |
+
+### GraphQL Schema
+
+| 面向 | 細節 |
+|--------|---------|
+| **File Types** | `.graphql`、`.gql` |
+| **Best For** | GraphQL APIs |
+| **Tools** | GraphQL Playground、Apollo Studio |
+
+### AsyncAPI
+
+| 面向 | 細節 |
+|--------|---------|
+| **Versions** | 2.x、3.x |
+| **Best For** | 事件驅動 API |
+| **Tools** | AsyncAPI Studio |
+
+## OpenAPI 結構範例
+
+```yaml
+openapi: "3.1.0"
+info:
+  title: API Name
+  version: "1.0.0"
+  description: API description
+
+servers:
+  - url: https://api.example.com/v1
+
+paths:
+  /users:
+    get:
+      summary: List users
+      responses:
+        "200":
+          description: Success
+
+components:
+  schemas:
+    User:
+      type: object
+      properties:
+        id:
+          type: string
+```
+
+## 文件元素
+
+### Required
+
+- Endpoint URL
+- HTTP method
+- Request 參數
+- Response 格式
+- Error codes
+- Authentication
+
+### Recommended
+
+- 程式碼範例（多種語言）
+- Rate limits
+- 分頁細節
+- Changelog／versioning
+
+### Optional
+
+- Try-it-out console
+- SDKs
+- Postman collections
+
+## Endpoint 文件範例
+
+```markdown
+## Create User
+
+Creates a new user account.
+
+**Endpoint:** `POST /users`
+
+**Authentication:** Bearer token required
+
+### Request Body
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| name | string | Yes | User's full name |
+| email | string | Yes | Email address |
+
+### Response
+
+{
+  "id": "usr_123",
+  "name": "John Doe",
+  "email": "john@example.com",
+  "createdAt": "2025-01-15T10:30:00Z"
+}
+
+### Errors
+
+| Code | Description |
+|------|-------------|
+| 400 | Invalid request body |
+| 409 | Email already exists |
+```
+
+## 工具
+
+### Generators
+
+| Tool | 用途 |
+|------|---------|
+| swagger-codegen | 產生 client SDKs |
+| openapi-generator | 產生 client／server 程式碼 |
+| typedoc | 產生 TypeScript 文件 |
+
+### Hosting
+
+| Tool | 類型 |
+|------|------|
+| Swagger UI | 自架 |
+| Redoc | 自架 |
+| ReadMe | SaaS |
+| Stoplight | SaaS |
+
+## 規則
+
+| 規則 | 描述 | 優先級 |
+|------|-------------|----------|
+| Document all endpoints | 為每一個公開 endpoint 撰寫文件 | Required |
+| Include examples | 納入 request 與 response 範例 | Required |
+| Document errors | 列出所有可能的 error response | Required |
+| Version sync | 讓文件與 API 版本保持同步 | Required |
+| Auth first | 在 endpoint 之前先記錄 authentication | Recommended |
+
+## 相關選項
+
+- [Markdown Docs](./markdown-docs.md) - 純 Markdown 文件
+- [Wiki Style](./wiki-style.md) - Wiki 風格的協作文件
+
+---
+
+## 參考資料
+
+- [OpenAPI Specification](https://spec.openapis.org/oas/latest.html)
+- [Swagger](https://swagger.io/)
+- [AsyncAPI](https://www.asyncapi.com/)
+
+---
+
+## 授權
+
+本文件以 [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) 釋出。
+
+**來源**: [universal-dev-standards](https://github.com/AsiaOstrich/universal-dev-standards)

package/bundled/locales/zh-TW/options/documentation/markdown-docs.md

@@ -0,0 +1,150 @@
+---
+source: options/documentation/markdown-docs.md
+source_version: 1.0.0
+translation_version: 1.0.0
+status: current
+---
+
+# Markdown 文件
+
+> **語言**: [English](../../../../options/documentation/markdown-docs.md) | 繁體中文
+
+**上層標準**: [Documentation Structure](../../core/documentation-structure.md)
+
+---
+
+## 概觀
+
+純 Markdown 文件是一種簡單、可攜的專案文件方式。檔案直接儲存在儲存庫中，以 Git 進行版本控制，並可在 GitHub 和 GitLab 等平台上原生呈現。
+
+## 最適用於
+
+- 開源專案
+- 託管於 GitHub/GitLab 的專案
+- 以開發者為中心的文件
+- 想要簡單、可攜文件的專案
+- 中小型專案
+
+## 檔案結構
+
+### 根目錄檔案
+
+| File | Required | 用途 |
+|------|----------|---------|
+| `README.md` | Yes | 專案概覽、快速開始 |
+| `CONTRIBUTING.md` | No | 貢獻指南 |
+| `CHANGELOG.md` | No | 版本歷史 |
+| `LICENSE` | Yes | 授權檔案 |
+
+### docs/ 資料夾
+
+**位置：** `docs/`
+**命名慣例：** lowercase-kebab-case
+
+#### 常見檔案
+
+- `getting-started.md`
+- `installation.md`
+- `configuration.md`
+- `api-reference.md`
+- `troubleshooting.md`
+- `faq.md`
+
+#### 子目錄
+
+| Directory | 用途 |
+|-----------|---------|
+| `guides/` | 操作指南 |
+| `tutorials/` | 逐步教學 |
+| `reference/` | API 與配置參考 |
+| `ADR/` | 架構決策記錄 |
+
+## README 範本
+
+```markdown
+# Project Name
+
+Brief description of the project.
+
+## Features
+
+- Feature 1
+- Feature 2
+
+## Installation
+
+npm install project-name
+
+## Quick Start
+
+import { something } from 'project-name';
+
+## Documentation
+
+See [docs/](./docs/) for full documentation.
+
+## Contributing
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md).
+
+## License
+
+[MIT](./LICENSE)
+```
+
+## Markdown 最佳實踐
+
+- 使用 ATX 樣式標題（`#`、`##`、`###`）
+- 在標題前後加入空白行
+- 使用指定語言的 fenced code block
+- 將每行控制在 120 字元以內
+- 對重複的 URL 使用 reference-style 連結
+
+## 工具
+
+| Tool | 用途 |
+|------|---------|
+| markdownlint | Lint markdown 檔案 |
+| markdown-link-check | 檢查失效連結 |
+| docsify | 產生文件網站 |
+| mkdocs | 靜態網站產生器 |
+
+## 規則
+
+| 規則 | 說明 | 優先順序 |
+|------|-------------|----------|
+| 根目錄大寫 | 根目錄文件使用 UPPERCASE（README、CONTRIBUTING） | Required |
+| docs lowercase-kebab | docs/ 檔案使用 lowercase-kebab-case | Required |
+| 相對連結 | 內部連結使用相對路徑 | Required |
+| 包含範例 | 為所有功能包含程式碼範例 | Recommended |
+
+## 與其他方式的比較
+
+| 面向 | 儲存庫內 Markdown | Wiki | 外部文件網站 |
+|--------|------------------|------|-------------------|
+| 版本控制 | 以 Git 為基礎 | 內建 | 視平台而定 |
+| 編輯 | 需要 Git | WYSIWYG／簡易 | 不一定 |
+| 離線存取 | 完整 | 有限 | 有限 |
+| 搜尋 | GitHub 搜尋 | 內建 | 不一定 |
+
+## 相關選項
+
+- [API Docs](./api-docs.md) - API 參考文件
+- [Wiki Style](./wiki-style.md) - Wiki 風格協作文件
+
+---
+
+## 參考資料
+
+- [CommonMark](https://commonmark.org/)
+- [GitHub Flavored Markdown](https://github.github.com/gfm/)
+- [Docsify](https://docsify.js.org/)
+- [MkDocs](https://www.mkdocs.org/)
+
+---
+
+## 授權
+
+本文件以 [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) 釋出。
+
+**來源**: [universal-dev-standards](https://github.com/AsiaOstrich/universal-dev-standards)

package/bundled/locales/zh-TW/options/documentation/wiki-style.md

@@ -0,0 +1,131 @@
+---
+source: options/documentation/wiki-style.md
+source_version: 1.0.0
+translation_version: 1.0.0
+status: current
+---
+
+# Wiki 風格文件
+
+> **語言**: [English](../../../../options/documentation/wiki-style.md) | 繁體中文
+
+**上層標準**: [Documentation Structure](../../core/documentation-structure.md)
+
+---
+
+## 概觀
+
+Wiki 風格文件提供一個可協作、易於編輯的知識庫。它非常適合內部文件、團隊知識分享，以及需要由多位貢獻者頻繁更新的內容。
+
+## 最適用於
+
+- 大型團隊
+- 內部文件
+- 知識庫
+- 頻繁更新的內容
+- 跨職能團隊
+
+## 平台
+
+| 平台 | 廠商 | 最適用於 | 主要特性 |
+|----------|--------|----------|--------------|
+| **Confluence** | Atlassian | 使用 Jira 的企業團隊 | 豐富的編輯器、範本、空間、權限 |
+| **Notion** | Notion Labs | 新創公司、彈性需求 | 資料庫、範本、巢狀頁面、留言 |
+| **GitHub Wiki** | GitHub | 開源、開發者 | 以 Git 為後盾、Markdown、隨 repo 免費 |
+| **GitBook** | GitBook | 公開文件 | Git 同步、精美 UI、支援 API docs |
+
+## 結構
+
+### 頂層空間
+
+| 空間 | 內容 |
+|-------|---------|
+| **Engineering** | 架構決策、技術標準、runbook |
+| **Product** | 功能規格、roadmap、使用者研究 |
+| **Team** | 新人上手、流程、會議紀錄 |
+
+### 頁面階層
+
+1. 概觀／索引頁
+2. 分類頁
+3. 細節頁
+4. 相關連結
+
+## 頁面範本
+
+```markdown
+# Page Title
+
+**Last Updated:** YYYY-MM-DD
+**Owner:** @username
+
+## Overview
+
+Brief description of what this page covers.
+
+## Content
+
+Main content here...
+
+## Related Pages
+
+- [Related Page 1](link)
+- [Related Page 2](link)
+
+## Changelog
+
+| Date | Author | Change |
+|------|--------|--------|
+| YYYY-MM-DD | @user | Initial creation |
+```
+
+## 最佳實踐
+
+- 為常見的頁面類型建立範本
+- 使用一致的命名慣例
+- 移動頁面時設定轉址
+- 定期進行內容稽核
+- 鼓勵留言與提問
+- 在頁面之間慷慨地建立連結
+
+## 規則
+
+| 規則 | 描述 | 優先級 |
+|------|-------------|----------|
+| 頁面歸屬 | 指派一位負責人維持內容時效性 | Required |
+| 頁面日期 | 標註最後更新日期 | Required |
+| 連結相關內容 | 連結到相關頁面以提升可發現性 | Recommended |
+| 季度審查 | 審查並更新陳舊內容 | Recommended |
+| 封存過時內容 | 封存而非刪除舊內容 | Recommended |
+
+## 與其他做法的比較
+
+| 面向 | Wiki | Repo 中的 Markdown | 外部文件網站 |
+|--------|------|------------------|-------------------|
+| 編輯 | WYSIWYG／容易 | 需要 Git 知識 | 視情況而定 |
+| 版本控制 | 內建 | 以 Git 為基礎 | 視平台而定 |
+| 協作 | 優異 | 良好 | 良好 |
+| 搜尋 | 內建 | GitHub 搜尋 | 視情況而定 |
+| 存取控制 | 細緻 | repo 層級 | 視情況而定 |
+| 離線存取 | 有限 | 完整 | 有限 |
+
+## 相關選項
+
+- [API Docs](./api-docs.md) - API 參考文件
+- [Markdown Docs](./markdown-docs.md) - 純 Markdown 文件
+
+---
+
+## 參考資料
+
+- [Confluence](https://www.atlassian.com/software/confluence)
+- [Notion](https://www.notion.so/)
+- [GitBook](https://www.gitbook.com/)
+
+---
+
+## 授權
+
+本文件依 [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) 釋出。
+
+**來源**: [universal-dev-standards](https://github.com/AsiaOstrich/universal-dev-standards)