如何參與 Poetry

參與 Poetry #

首先，感謝您撥冗參與！

以下是參與 GitHub 上的 Poetry 的一組準則。這些大多是準則，而非規則。請自行評估，並歡迎在 Pull Request 中為這份文件提出變更建議。

參與方式 #

回報錯誤 #

本節會指導您如何提交 Poetry 的錯誤回報。請遵守這些準則，讓維護者和社群瞭解您的回報、重現行為，並找出相關回報。

提交錯誤回報之前 #

• 查看 常見問題，瞭解常見問題和問題清單。
• 查看 部落格，瞭解最近發行的版本資訊，包含升級步驟與已知問題。
• 查看您的問題是否已存在於 問題追蹤 中。
• 確認您的問題真的是錯誤，而不是更適合在 討論 或 Discord 中提出的支援要求或問題。

如何提交錯誤回報？ #

關於 Poetry 和 poetry-core 錯誤，應該提交至主 問題追蹤，並使用正確的 問題範本。

說明問題，使其他人容易搜尋並了解

• 使用一個明確且具描述性的標題，針對問題識別問題。
• 描述可重現這個問題確切步驟，並提供盡可能多的細節。
• 描述您在執行步驟後觀察到的行為，並指出這是一個問題。
• 說明您預期看到的行為，以及原因為何。
• 如果問題包含意外產生的錯誤，請於debug模式（具有-vvv標誌）執行有問題的指令。

提供重現您問題的詳細步驟

• 提供您的pyproject.toml檔案，在Gist、pastebin或範例存放庫中移除可能的私人資訊，例如私人套件存放庫或名稱。
• 提供特定範例來展示重現問題的步驟。它可以是一個範例存放庫、在容器中執行的步驟順序，或僅是一個針對非常簡單案例的pyproject.toml。
• 您是否無法可靠地重現問題？如果無法，請提供有關問題發生的頻率和常發生的條件的詳細資訊。

透過回答這些問題提供更多背景資訊

• 問題最近才開始發生（例如更新到新版的Poetry之後）還是始終是一個問題？
• 如果問題最近才開始發生，您是否可以在舊版的Poetry中重現問題？問題未發生的最新版本為何？
• 您的環境中是否有任何特別或不尋常之處？這可能包括使用特殊容器映像、較新的CPU 架構（例如Apple Silicon）或會攔截或修改網路流量的公司代理程式。

包含關於您的組態和環境的詳細資訊

• 您使用的是Poetry 的哪個版本？您可以透過執行poetry --version 來取得確切版本。
• 執行Poetry時使用的是Python的哪個版本？執行poetry debug info取得這些資訊。
• 您所使用的作業系統的名稱及版本為何？範例包括Ubuntu 22.04或macOS 12.6。

為了讓其他人有最佳的機會了解並重現您的問題，請務必針對您的重現步驟投入更多心力。您可以在自己家中的本地端排除組態問題，並確保其他人可以在乾淨的容器（或VM）中清楚地重現您的問題，並在您的問題回報中提供您在該容器/VM中執行步驟。

建議加強 #

本節將引導您提交 Poetry 的改進建議，包含全新功能以及對既有功能的改善。遵循這些指南有助維護人員和社群了解您的建議，並找出相關建議。

在提交建議的改善之前#

• 查看 常見問題，瞭解常見問題和問題清單。
• 查看您的問題是否已存在於 問題追蹤 中。

如何提交建議的改善？#

關於 Poetry 和 poetry-core 的建議改善應提交至主要問題追蹤，使用正確的問題範本。

• 為此問題使用一個清楚且描述性的標題以識別建議。
• 提供建議改善的詳細說明，若可能請附上具體步驟或範例。
• 說明目前的行為並解釋您希望看到的改善以及原因。

文件貢獻#

開始貢獻專案最簡單的方法之一，就是透過改善文件。Poetry 不斷在演進，這表示我們的文件偶爾會有所遺漏。您可以透過新增遺漏的部分，編輯現有內容使其更容易閱讀，或建立新的內容，例如教學、常見問題等，來協助我們。

與文件相關的問題通常標示為area/docs 標籤，這也會觸發本網站所呈現的變更預覽。

程式碼貢獻#

挑選問題#

如果您想處理某個問題，請在問題上留言標記@python-poetry/triage。我們非常樂意在問題上討論解決方案。如果您需要協助設定程式碼庫，正在尋找要執行的專案，或希望取得設計或變更的回饋，請加入我們的Discord 伺服器或開始討論。

本地開發#

Poetry 是使用 Poetry 開發的。請參閱文件以在您的本地環境中安裝 Poetry。

您應先 Fork Poetry 存放庫，然後在本地複製它，才能對專案提出 Pull 要求。如果您不熟悉 Git 和基於 Pull 要求的開發，GitHub 提供了 指南，可能會對您有幫助。

接著您應安裝 Poetry 的依賴項，並執行測試套件，以確保所有內容運作正常。

poetry install
poetry run pytest

當您提供 Poetry 貢獻時，系統會執行自動化工具來確保您的程式碼適合合併。除了 pytest 外，您還需要確定您的程式碼使用 mypy 進行類型檢查後執行正常。

poetry run mypy

最後，系統會在您的程式碼上執行許多程式碼檢查工具，以嘗試確保程式碼樣式一致，並找出常見的錯誤。pre-commit 工具用於安裝和執行這些工具，並需要執行一次性設定。

poetry run pre-commit install

每次您提交時，pre-commit 現在都會執行並檢查您的程式碼。預設只會對變更的檔案執行，但您可以手動對所有檔案執行（如果您變更了 pre-commit 組態，這可能會很有用）。

poetry run pre-commit run --all-files

Pull 要求 #

• 完整填寫 Pull 要求主體，並盡可能精確地敘述您的變更。Pull 要求主體應保持最新，因為它通常會構成最終合併提交和變更日誌項目的基礎。
• 請務必讓您的 Pull 要求包含涵蓋變更或新增程式碼的測試。一般來說，程式碼才具有可合併性就需要測試，而沒有通過測試的程式碼不會被合併。
• 確保您的 Pull 要求通過 mypy 和 pre-commit 核對。請記得，您可以自行在本地執行這些工具，而不必依賴遠端 CI。
• 如果您的變更需要變更文件，則 Pull 要求也必須更新文件。請務必檢閱 CI 生成的文件預覽，是否有任何呈現問題。

所有 Pull 要求，除非另有指示，否則都需要先接受到 main 分支中。維護人員通常會決定是否需要將任何回傳移植到其他分支中，並在需要時執行。

問題分流 #

如果你協助分類已回報的問題，此部分提供一些有用的資訊，協助你為社群做出貢獻。

分類步驟 #

1. 判斷此問題與 Poetry 的哪個區域和版本相關，並設定適當的標籤（例如 version/x.x.x、area/docs、area/venv），並移除 status/triage 標籤。
2. 如果未提供已請求的資訊（例如偵錯日誌、pyproject.toml 等）且與問題相關，請向作者請求。
   1. 在等待作者回覆時，設定 status/waiting-on-response 標籤。
3. 嘗試用已回報的 Poetry 版本重現問題，或向作者請求進一步的說明。
4. 確保問題尚未解決。嘗試在最新的穩定版本、最新的預發行版本（若有）和開發分支中重現問題。
5. 如果無法重現問題，
   1. 請求問題作者提供更多重現步驟和說明，
   2. 設定 status/needs-reproduction 標籤，
   3. 如果無法進行重現，請關閉問題。
6. 如果可以重現問題，
   1. 在問題中留言確認，
   2. 設定 status/confirmed 標籤，
   3. 如果可能，找出此問題的根本原因，
   4. 如果有興趣，嘗試透過 pull request 修復問題。

多版本 #

在嘗試重現問題時，你經常會希望同時使用多個版本的 Poetry。pipx 讓這件事變得簡單。

pipx install --suffix @1.2.1 'poetry==1.2.1'
pipx install --suffix @1.3.0rc1 'poetry==1.3.0rc1'
pipx install --suffix @main 'poetry @ git+https://github.com/python-poetry/poetry'
pipx install --suffix @local '/path/to/local/clone/of/poetry'

# now you can use any of the chosen versions of Poetry with their configured suffix, e.g.
poetry@main --version

pipx install --suffix @pr1234 git+https://github.com/python-poetry/poetry.git@refs/pull/1234/head