CONTRIBUTING_zh_tw.md

English | 简中 | 繁中

✨
貢獻指南

我們非常榮幸並感激您願意為本項目做出貢獻。

為確保您的努力能夠順利融入項目並惠及整個社區，我们制定這份指南，來幫助您更好的理解我们的標準和流程。

建議您認真閱讀以下内容，它们旨在助您高效工作，並確保您的成果符合我们的要求和規範。

斜體部分屬於建議，其餘屬於要求，均作為您開發過程中，及插件庫維護者審酌 PR 時的參考。請特別注意加粗部分。

希望這份指南能成為您的良好起點！

🔧 添加或修改插件？

🤔 插件適合入庫吗？

不要急於求成。在創作並提交新插件之前，思考如下問題：

• 你的插件是否為打包插件？——單文件插件和文件夾插件不可入庫；
• 是否已經存在功能極度相似的插件？——無意義的重複輪子不可取；
• 你的代碼是否有必要作為 MCDR 插件提供？是否更適合 PyPI？——考慮使用目的，確保它有必要；
• 插件泛用性是否足夠？是否有足夠的理由讓新用戶選擇你的插件？——不要將僅供自用或完全不實用的插件提交到插件庫；
• 你的項目準備好進入公眾測試（Beta）階段了嗎？——如果它還處於早期版本，請先將其完善。我们建議您在提交時保證插件已有一個可用 Release。

⚖️ 版權意識很重要

為保證提交正確，我們希望您能符合以下身份之一：

• 插件的作者、維護者或是被授權的協作者；
• 獲作者、維護者或協作者明確書面許可的上傳者。

若您的插件中參考或包含其他項目的代碼：

• 對於開源代碼，請務必遵守相應的開源許可證；
• 使用閉源代碼時，請確認自己擁有使用權，並嚴格遵守相關協議。

我們強烈建議您 使用開源許可，以保護您和他人的權利。插件庫腳本和 MCDR 對您倉庫執行的操作應與所有 OSI 批准的許可相兼容。

否則，請理解並知悉：

• 通過提交您的插件至插件庫，您在專有協議或許可之外（如果有），授予任何實體直接或間接的從 Github Releases 下載和使用您插件的權利；
• 您的提交請求可能需要更長的處理時間。

🌟 前置工作要注意

• 插件名稱和 ID 不要與其他插件太過相似；
  作為參考，一種量化標準為：轉為小寫的插件名稱和 ID 與其他插件相應字段的 萊文斯坦距離 不應小於 3
• 在相應字段中明確聲明前置插件和 Python 包，
  留意你的插件是否是用了新版本 MCDR 特有的接口，按需聲明 MCDR 版本；
• 確保你的插件在目標平台上可以正常工作。

✒️ 插件信息要寫對

按照 文檔 中的說明創建或編輯 plugin_info.json。

• 參照已有插件和文檔，檢查 label 字段是否合適；
• 插件 README 應當放置於 related_path 中且命名為 README.md（不分大小寫）；
• 插件 ID 必須在各個環節保持一致；
• description 和 introduction 字段應當正確，至少提供一種語言。

📢 插件介紹要寫好

良好且詳細的介紹是成為有秀插件的條件之一。

• 在 README 或文檔中，詳細闡釋插件的環境要求、功能、特徵、用法等；
• 在 description 中用一句話簡單概括插件的作用；
• 在 introduction 中介绍插件的特點，或直接指向 README 文件。

🔂 一個 PR 一件事

• 添加插件時，請將多個插件分開 PR；
• 修改插件時，相同作者多個插件的相同字段修改可以合併在一個 PR 中；
• 删除插件時，相同作者的多個插件可以合併在一個 PR 中。

⏳ 交了 PR 别著急

提交 PR 後，插件庫維護者將盡快審酌您的插件。他們將根據自動檢查結果、該指南和個人判斷，给出相應的反饋。如果他們無法做出決定，您的 PR 可能交予上一級維護者處理。在這一過程中，您可以自行决定是否採納他们的建議（如果有）。这些建議可能幫助您的插件更加順暢的並入插件庫。

📦 發版本時要小心

参照 文檔 發布插件版本。

• Release Tag 必須正確填寫，否則插件庫舞法獲取版本地址；
• 將打包插件（.mcdr 或 .pyz）作為附件上傳。

🛠️ 貢獻腳本或工作流？

• 建議先創建 Issue，描述問題或需求，再創建與之關聯的 PR；
• 所有修改應當合併到 master 分支。

此文檔最初使用 zh_cn 撰寫。如有任何疑問，歡迎在 Issue 中提出。