Skip to content

貢獻指南

如何為 Potato 標註工具做出貢獻。

Potato 是完全開源的，歡迎社群貢獻。本指南介紹如何有效地參與貢獻。

入門

前提條件

  • Python 3.7+
  • Git
  • GitHub 賬戶

設定開發環境

  1. 在 GitHub 上 Fork 倉庫

  2. 克隆你的 Fork：

    bash
    git clone https://github.com/YOUR_USERNAME/potato.git
cd potato

  3. 安裝依賴：

    bash
    pip install -r requirements.txt
pip install -r requirements-test.txt  # For running tests

  4. 執行測試確保一切正常：

    bash
    pytest

貢獻方式

報告 Bug

發現了 Bug？提交 Issue，需包含：

  • 清晰、描述性的標題
  • 重現問題的步驟
  • 預期行為與實際行為
  • 你的環境資訊（Python 版本、作業系統、瀏覽器等）
  • 可用的錯誤訊息或日誌

建議新功能

有改進的想法？提交功能請求，描述：

  • 你想要解決的問題
  • 你提議的解決方案
  • 為什麼這對其他使用者有益

提交程式碼

  1. 為你的更改建立分支：

    bash
    git checkout -b feature/your-feature-name

  2. 進行更改，遵循編碼規範

  3. 為新功能編寫測試

  4. 執行測試套件：

    bash
    pytest tests/unit/ -v      # Fast unit tests
pytest tests/server/ -v    # Integration tests

  5. 提交更改並附上描述性訊息：

    bash
    git commit -m "Add feature: brief description of changes"

  6. 推送到你的 Fork：

    bash
    git push origin feature/your-feature-name

  7. 在 GitHub 上建立 Pull Request

編碼規範

Python 風格

  • 遵循 PEP 8 風格指南
  • 使用有意義的變數和函式名
  • 為公共函式和類新增文件字串
  • 保持函式專注且大小適當

文件

新增或修改功能時：

  1. 更新 docs/ 目錄中的相關文件
  2. 新增或更新 project-hub/simple_examples/ 中的示例配置
  3. 為複雜邏輯新增行內註釋

測試

  • 為新功能和 Bug 修復編寫測試
  • 將單元測試放在 tests/unit/ 中
  • 將整合測試放在 tests/server/ 中
  • 確保提交 PR 前所有測試通過

文件指南

每個主要功能應包含：

  1. 管理員文件（docs/）：

    • 配置選項和預設值
    • YAML 示例
    • 故障排除提示

  2. 示例項目（project-hub/simple_examples/）：

    • 可執行的配置檔案
    • 示例資料檔案
    • 如果複雜則附帶 README

文件風格

  • 使用正確的 YAML 語法（而非 JSON 風格）
  • 包含完整、可執行的示例
  • 交叉引用相關文件
  • 為 UI 功能新增截圖

Pull Request 指南

提交前

  • 本地測試通過（pytest）
  • 程式碼遵循項目風格
  • 文件已更新
  • 提交訊息清晰
  • 分支與 main 保持同步

PR 描述

包含：

  • PR 做了什麼
  • 為什麼需要這個更改
  • 如何測試這些更改
  • UI 更改的截圖

開發路線圖

當前開發優先順序：

  1. 增強 UI/UX 改進
  2. 額外的標註模式類型
  3. 更好的 AI 整合選項
  4. 效能最佳化
  5. 文件改進

獲取幫助

行為準則

請在所有互動中保持尊重和建設性。我們都在為改善 Potato 而努力。

許可證

通過為 Potato 做貢獻，你同意你的貢獻將按照項目現有許可證進行授權。

感謝你為 Potato 做貢獻！

有關更多詳情，請參閱原始碼文件。