問題報告指南

有效的漏洞報告和功能請求對 XOOPS 開發至關重要。本指南幫助您創建高質量的問題。

報告前

檢查現有問題

始終首先搜索：

前往 GitHub Issues
搜索與您的問題相關的關鍵字
檢查已關閉的問題 - 可能已解決
查看拉取請求 - 可能正在進行

使用搜索過濾器：

is:issue is:open label:bug - 開放漏洞
is:issue is:open label:feature - 開放功能請求
is:issue sort:updated - 最近更新的問題

這真的是問題嗎？

首先考慮：

配置問題？ - 檢查文檔
使用問題？ - 在論壇或 Discord 社區上提問
安全問題？ - 見下面的 #安全問題部分
特定模塊？ - 向模塊維護者報告
特定主題？ - 向主題作者報告

問題類型

漏洞報告

漏洞是意外行為或缺陷。

示例：

登錄不工作
數據庫錯誤
缺失表單驗證
安全漏洞

功能請求

功能請求是新功能的建議。

示例：

添加新功能支持
改進現有功能
添加缺失文檔
性能改進

增強

增強改進現有功能。

示例：

更好的錯誤消息
改進的性能
更好的 API 設計
更好的用戶體驗

文檔

文檔問題包括缺失或不正確的文檔。

示例：

不完整的 API 文檔
過時的指南
缺失代碼示例
文檔中的拼寫錯誤

報告漏洞

漏洞報告模板

## 描述
簡明清晰的漏洞描述。

## 重現步驟
1. 步驟一
2. 步驟二
3. 步驟三

## 預期行為
應該發生什麼。

## 實際行為
實際發生了什麼。

## 環境
- XOOPS 版本: X.Y.Z
- PHP 版本: 8.2/8.3/8.4
- 數據庫: MySQL/MariaDB 版本
- 操作系統: Windows/macOS/Linux
- 瀏覽器: Chrome/Firefox/Safari

## 屏幕截圖
如果適用，添加顯示問題的屏幕截圖。

## 附加背景
任何其他相關信息。

## 可能的修復
如果您有修復問題的建議（可選）。

好的漏洞報告示例

## 描述
當數據庫連接失敗時，登錄頁面顯示空白頁面。

## 重現步驟
1. 停止 MySQL 服務
2. 導航到登錄頁面
3. 觀察行為

## 預期行為
顯示用戶友好的錯誤消息，解釋數據庫連接問題。

## 實際行為
頁面完全空白 - 沒有錯誤消息，沒有可見的界面。

## 環境
- XOOPS 版本: 2.7.0
- PHP 版本: 8.0.28
- 數據庫: MySQL 5.7
- 操作系統: Ubuntu 20.04
- 瀏覽器: Chrome 120

## 附加背景
這可能影響其他頁面。錯誤應向管理員顯示或適當記錄。

## 可能的修復
在渲染模板之前檢查 header.php 中的數據庫連接。

糟糕的漏洞報告示例

## 描述
登錄不工作

## 重現步驟
它不工作

## 預期行為
它應該工作

## 實際行為
它不工作

## 環境
最新版本

報告功能請求

功能請求模板

## 描述
功能的清晰、簡潔描述。

## 問題陳述
為什麼需要此功能？它解決了什麼問題？

## 建議解決方案
描述您理想的實現或 UX。

## 考慮的替代方案
還有其他方式來實現此目標嗎？

## 附加背景
任何模型、示例或參考。

## 預期影響
這將如何使用戶受益？會破壞什麼嗎？

好的功能請求示例

## 描述
為用戶帳戶添加雙因素身份驗證 (2FA)。

## 問題陳述
隨著安全漏洞的增加，許多 CMS 平台現在提供 2FA。XOOPS 用戶希望獲得超越密碼的更強帳戶安全性。

## 建議解決方案
實現基於 TOTP 的 2FA（與 Google Authenticator、Authy 等兼容）。
- 用戶可以在其配置文件中啟用 2FA
- 顯示設置的二維碼
- 生成備用恢復代碼
- 在登錄時要求 2FA 代碼

## 考慮的替代方案
- 基於短信的 2FA（需要運營商集成，不太安全）
- 硬件密鑰（對普通用戶來說過於複雜）

## 附加背景
與 GitHub、GitLab 和 WordPress 實現相似。
參考：[TOTP 標準 RFC 6238](https://tools.ietf.org/html/rfc6238)

## 預期影響
增加帳戶安全性。最初可能是可選的，未來版本強制。

安全問題

不要公開報告

絕不為安全漏洞創建公開問題。

私下報告

發電子郵件給安全團隊： security@xoops.org
包括：
- 漏洞描述
- 重現步驟
- 潛在影響
- 您的聯繫信息

負責任的披露

我們將在 48 小時內確認收據
我們將每 7 天提供一次更新
我們將制定修復時間表
您可以請求發現的信用
協調公開披露時間

安全問題示例

主題: [SECURITY] 評論表單中的 XSS 漏洞

描述:
Publisher 模塊中的評論表單沒有正確轉義用戶輸入，
允許存儲 XSS 攻擊。

重現步驟:
1. 創建評論內容: <img src=x onerror="alert('xss')">
2. 提交表單
3. 查看評論時 JavaScript 執行

影響:
攻擊者可以盜取用戶會話令牌、以用戶身份執行操作，
或破壞網站。

環境:
- XOOPS 2.7.0
- Publisher 模塊 1.x

問題標題最佳實踐

好的標題

✅ 當數據庫連接失敗時登錄頁面顯示空白錯誤
✅ 添加雙因素身份驗證支持
✅ 表單驗證未防止名稱字段中的 SQL 注入
✅ 改進用戶列表查詢的性能
✅ 更新 PHP 8.2 安裝文檔

糟糕的標題

❌ 系統中的漏洞
❌ 幫幫我!!
❌ 它不工作
❌ 關於 XOOPS 的問題
❌ 錯誤

標題指南

具體明確 - 提及內容和位置
簡明扼要 - 在 75 個字符以內
使用現在時態 - “顯示空白頁面” 而不是 “顯示了空白”
包括背景 - “在管理面板中”、“安裝期間”
避免通用詞 - 不是 “修復”、“幫助”、“問題”

問題描述最佳實踐

包括必要信息

什麼 - 問題的清晰描述
哪裡 - 哪個頁面、模塊或功能
何時 - 重現步驟
環境 - 版本、OS、瀏覽器、PHP
為什麼 - 為什麼這很重要

使用代碼格式

錯誤消息: `Error: Cannot find user`

代碼片段:
```php
$user = $this->getUser($id);
if (!$user) {
    echo "Error: Cannot find user";
}

### 包括屏幕截圖

對於 UI 問題，請包括：
- 問題的屏幕截圖
- 預期行為的屏幕截圖
- 標註什麼是錯誤的（箭頭、圓圈）

### 使用標籤

添加標籤以分類：
- `bug` - 漏洞報告
- `enhancement` - 增強請求
- `documentation` - 文檔問題
- `help wanted` - 尋求幫助
- `good first issue` - 適合新貢獻者

---

## 報告後

### 保持響應

- 檢查問題評論中的問題
- 如果要求，提供其他信息
- 測試建議的修復
- 驗證漏洞在新版本中仍然存在

### 遵循禮儀

- 尊重和專業
- 假設善意
- 不要要求修復 - 開發者是志願者
- 如果可能，提供幫助
- 感謝貢獻者的工作

### 保持問題專注

- 保持主題
- 不討論無關問題
- 改為鏈接相關問題
- 不要用問題進行功能投票

---

## 問題發生了什麼

### 分類過程

1. **創建新問題** - GitHub 通知維護者
2. **初步審查** - 檢查清晰度和重複
3. **標籤分配** - 分類並優先排序
4. **分配** - 如果適當，分配給某人
5. **討論** - 如果需要，收集其他信息

### 優先級別

- **關鍵** - 數據丟失、安全、完全破壞
- **高** - 主要功能損壞、影響許多用戶
- **中** - 部分功能損壞、有解決方案
- **低** - 小問題、美觀或小眾用途

### 解決結果

- **已修復** - 在 PR 中解決的問題
- **不會修復** - 因技術或戰略原因被拒絕
- **重複** - 與另一個問題相同
- **無效** - 實際上不是問題
- **需要更多信息** - 等待附加詳細信息

---

## 問題示例

### 示例：好的漏洞報告

```markdown
## 描述
使用啟用嚴格模式的 MySQL 時，管理員用戶無法刪除項目。

## 重現步驟
1. 在 MySQL 中啟用 `sql_mode='STRICT_TRANS_TABLES'`
2. 導航到 Publisher 管理面板
3. 單擊任何文章的刪除按鈕
4. 顯示錯誤

## 預期行為
應該刪除文章或顯示有意義的錯誤。

## 實際行為
錯誤: "SQL Error - Unknown column 'deleted_at' in ON clause"

## 環境
- XOOPS 版本: 2.7.0
- PHP 版本: 8.2.0
- 數據庫: MySQL 8.0.32 with STRICT_TRANS_TABLES
- 操作系統: Ubuntu 22.04
- 瀏覽器: Firefox 120

## 屏幕截圖
[錯誤消息的屏幕截圖]

## 附加背景
這只發生在嚴格 SQL 模式下。使用默認設置時工作正常。
查詢在 class/PublisherItem.php:248

## 可能的修復
在 'deleted_at' 周圍使用單引號或對所有列名使用反引號。

示例：好的功能請求

## 描述
為公開內容的只讀訪問添加 REST API 端點。

## 問題陳述
開發者希望使用 XOOPS 數據構建移動應用和外部服務。
目前僅限於已過時且文檔不完善的 SOAP API。

## 建議解決方案
使用以下功能實現 RESTful API：
- 文章、用戶、評論的端點（只讀）
- 基於令牌的身份驗證
- 標準 HTTP 狀態代碼和錯誤
- OpenAPI/Swagger 文檔
- 分頁支持

## 考慮的替代方案
- 增強的 SOAP API（遺留，不符合標準）
- GraphQL（更複雜，可能是未來）

## 附加背景
見 Publisher 模塊 API 重構以獲得類似模式。
將與現代網絡開發實踐保持一致。

## 預期影響
啟用第三方工具和移動應用的生態系統。
將改進 XOOPS 採用和生態系統。

問題報告指南

報告前

檢查現有問題

這真的是問題嗎？

問題類型

漏洞報告

功能請求

增強

文檔

報告漏洞

漏洞報告模板

好的漏洞報告示例

糟糕的漏洞報告示例

報告功能請求

功能請求模板

好的功能請求示例

安全問題

不要公開報告

私下報告

負責任的披露

安全問題示例

問題標題最佳實踐

好的標題

糟糕的標題

標題指南

問題描述最佳實踐

包括必要信息

使用代碼格式

示例：好的功能請求

相關文檔