錯誤回報與功能請求#

Arrow 仰賴使用者回饋來找出缺陷和改進機會。我們鼓勵所有使用者透過建立錯誤回報與功能請求或評論現有問題來參與。即使您無法自行貢獻問題的解決方案，您的回饋也能幫助我們了解問題並優先處理改進函式庫的工作。

GitHub 議題#

Arrow 專案使用 GitHub 議題 來追蹤問題 - 包括錯誤回報與功能請求。

建立議題#

Apache Arrow 依靠社群貢獻來解決回報的錯誤和功能請求。與大多數軟體專案一樣，貢獻者的時間和資源是有限的。以下指南旨在產生高品質的錯誤回報與功能請求，使社群貢獻者能夠更快地回應更多問題

檢查現有議題#

在您建立新議題之前，我們建議您先搜尋未解決的現有議題，以確認是否已有人回報相同的問題或功能請求。

議題描述#

清楚描述問題或請求的功能是任何議題最重要的元素。有效的描述可以幫助開發人員理解並有效處理回報的問題，並且可能包括以下內容

  • 清楚、簡潔的步驟來重現問題，並盡可能減少非 Arrow 的依賴性。 如果讀取檔案時發生問題，請盡可能提供小的範例檔案，或建立範例檔案的程式碼。如果您的錯誤回報說「嘗試讀取我的檔案時崩潰，但我無法與您分享檔案」，這會使我們很難進行偵錯。

  • 任何相關的作業系統、語言和函式庫版本資訊

  • 如果不清楚，請明確說明預期的行為以及實際發生的情況。

  • 避免在單一議題中塞入多個問題或功能請求。每個議題應處理單一錯誤或功能。

如果開發人員無法取得失敗的單元測試，他們將無法知道問題已被識別，也無法知道問題何時已修復。請嘗試預期那些試圖理解問題的人可能會問您的問題，並預先提供這些支援細節。

良好的錯誤回報範例在下方

具有時區錯誤的時間戳記的 print 方法

import pyarrow as pa

a = pa.array([0], pa.timestamp('s', tz='+02:00'))

print(a) # representation not correct?
# <pyarrow.lib.TimestampArray object at 0x7f834c7cb9a8>
# [
#  1970-01-01 00:00:00
# ]

print(a[0])
#Traceback (most recent call last):
#  File "<stdin>", line 1, in <module>
#  File "pyarrow/scalar.pxi", line 80, in pyarrow.lib.Scalar.__repr__
#  File "pyarrow/scalar.pxi", line 463, in pyarrow.lib.TimestampScalar.as_py
#  File "pyarrow/scalar.pxi", line 393, in pyarrow.lib._datetime_from_int
#ValueError: fromutc: dt.tzinfo is not self

當來源資料為毫秒精度時，使用 col_types 選項 "T" 或 "t" 讀取 CSV 檔案時發生錯誤

library(arrow, warn.conflicts = FALSE)
tf <- tempfile()
write.csv(data.frame(x = '2018-10-07 19:04:05.005'), tf, row.names = FALSE)

# successfully read in file
read_csv_arrow(tf, as_data_frame = TRUE)
#> # A tibble: 1 × 1
#>   x
#>   <dttm>
#> 1 2018-10-07 20:04:05

# the unit here is seconds - doesn't work
read_csv_arrow(
  tf,
  col_names = "x",
  col_types = "T",
  skip = 1
)
#> Error in `handle_csv_read_error()`:
#> ! Invalid: In CSV column #0: CSV conversion error to timestamp[s]: invalid value '2018-10-07 19:04:05.005'

# the unit here is ms - doesn't work
read_csv_arrow(
  tf,
  col_names = "x",
  col_types = "t",
  skip = 1
)
#> Error in `handle_csv_read_error()`:
#> ! Invalid: In CSV column #0: CSV conversion error to time32[ms]: invalid value '2018-10-07 19:04:05.005'

# the unit here is inferred as ns - does work!
read_csv_arrow(
  tf,
  col_names = "x",
  col_types = "?",
  skip = 1,
  as_data_frame = FALSE
)
#> Table
#> 1 rows x 1 columns
#> $x <timestamp[ns]>

其他產生有用的錯誤回報的資源

識別 Arrow 組件#

Arrow 是一個廣泛的專案，支援多種語言並組織成許多組件。識別受影響的組件有助於讓新議題獲得適當貢獻者的關注。

  • 組件標籤，可以由 Apache Arrow 專案的提交者新增，用於指示您的議題所屬的專案領域（例如「Component: Python」或「Component: C++」）。

  • 在議題標題前加上方括號括住的組件名稱，例如 [Python] issue summary ；這有助於瀏覽開啟議題列表，並且也使我們的變更日誌更易於閱讀。大多數前綴與組件名稱完全相同，但以下例外情況除外

    • 組件： 持續整合 — 摘要前綴： [CI]

    • 組件： 開發者工具 — 摘要前綴： [Dev]

    • 組件： 文件 — 摘要前綴： [Docs]

議題生命週期#

錯誤回報與功能請求都遵循定義的生命週期。如果一個議題目前正在處理中，則應指派開發人員。當議題達到最終狀態時，它將以兩種結果之一關閉

  • 關閉為已完成 - 表示議題已完成；解決議題的 PR 應已由 GitHub 自動連結（假設 PR 正確提及議題編號）。

    如果您正在合併 PR，建議在連結的議題中新增評論，說明哪個 PR 正在解決它。這樣 GitHub 會為任何參與議題協作的人建立通知。

  • 關閉為未規劃 - 表示議題已關閉，不應再接收任何更新，但未採取任何行動。

議題指派#

指派表示承諾處理議題，貢獻者應在工作開始時自行指派議題。現在任何人都可以透過評論 take 來自行指派議題。