错误报告和功能请求#

Arrow 依靠用户反馈来识别缺陷和改进机会。鼓励所有用户通过创建错误报告和功能请求或评论现有问题来参与。即使您自己无法为问题贡献解决方案，您的反馈也能帮助我们了解问题并确定改进库工作的优先级。

GitHub Issues#

Arrow 项目使用 GitHub Issues 来跟踪问题 - 包括错误报告和功能请求。

创建 Issues#

Apache Arrow 依靠社区贡献来解决报告的错误和功能请求。与大多数软件项目一样，贡献者的時間和资源是有限的。以下准则旨在生成高质量的错误报告和功能请求，使社区贡献者能够更快地响应更多问题。

检查现有 Issues#

在创建新问题之前，我们建议您先搜索是否存在未解决的、描述相同问题或功能请求的现有 Issues。

问题描述#

对问题或请求的功能进行清晰的描述是任何 Issue 中最重要的元素。有效的描述可以帮助开发人员理解并有效地处理报告的问题，其中可能包括以下内容：

  • **清晰、最简化的重现问题的步骤，并尽量减少非 Arrow 依赖项。** 如果读取文件时出现问题，请尝试提供尽可能小的示例文件，或创建示例文件的代码。如果您的错误报告说“尝试读取我的文件时崩溃了，但我无法与您分享”，我们将很难进行调试。

  • 任何相关的操作系统、语言和库版本信息。

  • 如果预期行为和实际发生的情况不明确，请清晰地说明。

  • 避免在单个 Issue 中包含多个问题或功能请求。每个 Issue 应处理单个错误或功能。

如果开发人员无法获得失败的单元测试，他们将无法知道问题是否已被识别，也无法知道问题何时得到修复。尝试预测您可能会被试图理解该问题的人提出的问题，并预先提供这些支持细节。

以下是良好错误报告的示例：

带时区的時間戳的 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 项目的提交者添加，用于指示您的问题所属的项目区域（例如“组件：Python”或“组件：C++”）。

  • 在问题标题前加上括号中的组件名称，例如 [Python] 问题 摘要；这有助于浏览未解决问题的列表，也使我们的变更日志更具可读性。大多数前缀与**组件**名称完全相同，但以下情况除外：

    • **组件：** 持续集成 — **摘要前缀：** [CI]

    • **组件：** 开发者工具 — **摘要前缀：** [Dev]

    • **组件：** 文档 — **摘要前缀：** [Docs]

Issue 生命周期#

错误报告和功能请求都遵循定义的生命周期。如果某个 Issue 正在处理中，则应为其分配一名开发人员。当 Issue 达到最终状态时，它将以两种结果之一关闭：

  • **关闭为已完成** - 指示 Issue 已完成；解决 Issue 的 PR 应已由 GitHub 自动链接（假设 PR 正确地提到了 Issue 编号）。

    如果您正在合并 PR，则最好在链接的 Issue 中添加一条评论，说明哪个 PR 正在解决它。这样 GitHub 就会为任何参与该 Issue 的人创建一个通知。

  • **关闭为未计划** - 指示 Issue 已关闭，不应再接收任何更新，但*未采取任何行动*。

Issue 分配#

分配表示承诺处理某个 Issue，贡献者应在开始工作时自行分配 Issue。现在任何人都可以通过评论 take 来自行分配 Issue。