ARTICLE DETAIL

资讯详情

深耕网站建设、视觉设计与SEO优化的一线实战洞察。

Apache Arrow 贡献者沟通指南:从 Issue 到邮件列表的完整协作规范

Apache Arrow 贡献者沟通指南:从 Issue 到邮件列表的完整协作规范 Apache Arrow 贡献者沟通指南从 Issue 到邮件列表的完整协作规范【免费下载链接】arrowApache Arrow is the universal columnar format and multi-language toolbox for fast data interchange and in-memory analytics项目地址: https://gitcode.com/GitHub_Trending/arrow3/arrowApache Arrow 是一个横跨 C、Python、R、Ruby、Java、Rust 等多种语言的超大型开源项目任何单一背景的开发者都可能在协作中遇到自己不熟悉的领域。本文基于 新贡献者指南 中的Communication沟通章节整理而成系统介绍 Apache Arrow 社区推荐的沟通渠道、Issue 使用规范、邮件列表协作方式以及配套的学习资源。读完本文你将掌握如何正确提问、如何提交高质量的 Bug 报告与功能请求、如何认领 Issue 并参与社区讨论从而顺畅地融入 Arrow 的开发者协作流程。沟通的基础认知一个由专家与学习者共同组成的社区Apache Arrow 的贡献者群体中既有经验丰富的软件工程师和核心开发者也有大量普通用户、初学者与爱好者。社区官方对这一点有明确的定位——任何人都欢迎提问任何人都可能需要帮助项目规模庞大、覆盖语言众多每个人都会遇到需要学习的新事物即使是资深的 C 开发者也可能需要询问关于 R 或 Ruby 的基础问题社区鼓励开放沟通并承诺尽可能提供帮助。因此提问不是一件丢人的事。社区明确表示“我们都有愚蠢的问题我们也都经常需要帮助”见 communication.rst并希望通过开放的沟通氛围降低新贡献者的参与门槛。使用语言标签Tag标记你的沟通内容由于项目涉及多种语言和多个组件沟通时务必使用适当的标签tags标记你的消息例如[C]、[R]、[Ruby]等这样消息才能被对应领域的正确人群注意到。这一规范不仅适用于邮件列表也同样适用于 Issue 标题——在 Bug 报告与功能请求 文档中社区同样要求以组件名作为 Issue 标题前缀详见下文“Issue 标题规范”。到哪里寻求帮助三大沟通渠道对于任何问题社区提供了三类主要渠道你可以根据问题的性质选择渠道适用场景特点GitHub Issues提问、报告 Bug、提议新功能、提出较大的文档改动、报告构建问题与具体问题强绑定便于追踪与搜索GitHub Discussions提问、讨论、征求更广泛的反馈所有帖子会镜像同步到用户邮件列表用户/开发邮件列表向全体用户或开发者广播问题覆盖范围最广可触达所有订阅者以下是各渠道的详细说明。GitHub项目的沟通主阵地Apache Arrow 的项目托管在 GitHub 上社区主要使用三类 GitHub 功能进行沟通GitHub Issues用于提问、报告 Bug、提议新功能GitHub Discussions用于开放式讨论与提问Pull Requests用于提交已经写好的代码贡献。何时使用 GitHub Issues官方建议在以下场景创建 Issue提问ask questions报告 Bugreport a bug详见 如何写好 Bug 报告与功能请求提议一个新功能propose a new feature提议对文档进行较大的改动propose a bigger change in the documentation报告 Arrow 某个库的构建问题并讨论可能的解决方案也可以写邮件到 GitHub Discussions 或用户邮件列表。社区特别指出即使你对某些事情不确定创建 Issue 也是有用的——不仅对你个人有帮助对其他人和整个项目也同样有价值。注意在 Issue 描述中务必写清楚你使用的操作系统和Arrow 版本并附上调试信息/错误输出。这一要求与 Bug 报告指南 中“Issue 描述”一节的要求完全一致。从 Issue 到 Pull Request 的协作流程当你的新贡献已经写好时正确的流程是先创建一个 GitHub Issue在 Issue 中说明你计划如何实现让至少一位 Arrow 开发者认可你的基本方案后再动手——在投入大量时间之前先征询意见避免做社区认为“不太好的想法”确认方向后创建 Pull Request。如果你打算解决一个已存在的 Issue应当在 Issue 评论区与其他贡献者沟通交流说明你的意图。官方建议在开始工作时自行认领self-assign该 Issue任何人都可以通过在评论区留言take来认领详见下文“Issue 生命周期与认领”。邮件列表向全体社区广播问题邮件列表是 GitHub 之外另一条重要的沟通渠道你可以订阅用户user或开发development邮件列表浏览历史主题或直接提问与 GitHub 上只有被 提及或正在协作 PR 的人才能收到通知不同邮件列表可以向全体用户或开发者广播当你希望从更广泛的受众获得反馈或答案时应当使用邮件列表。GitHub Discussions 与用户邮件列表是镜像同步的GitHub Discussions 上的所有帖子都会镜像到userarrow.apache.org邮件列表用户可以在任一位置提出使用类问题。此外社区还设有双周一次的开发者同步电话会议biweekly developers sync call任何人都可以参加会议链接会在开发邮件列表上公布。关于 AI 工具的社区立场社区明确表示使用 AI 工具帮助润色措辞或语法完全没问题但社区希望听到的是你本人的声音而不是你的 AI 助手——请不要使用 AI 代替你生成提问或评论。这一立场在 开发者概览 的“AI-generated code”一节中有更完整的延伸AI 生成的 PR 若作者参与度过低可能被直接关闭而不再评审建议只提交你能自己调试并完全理解的改动并在 PR 中如实说明 AI 的使用情况。写出高质量的 Bug 报告与功能请求好的 Issue 描述是 Issue 中最关键的要素。根据 Bug 报告与功能请求指南一份有效的描述应当包含以下要素清晰、最小的可复现步骤且尽量少依赖非 Arrow 组件——例如读取文件出错时尽量提供最小化的示例文件或生成该文件的代码相关的操作系统、语言和库版本信息明确说明期望行为与实际发生的行为如果不明显的话一个 Issue 只处理一个问题不要把多个 Bug 或功能请求塞进同一个 Issue。社区反复强调如果开发者无法复现问题、无法得到一个失败的单元测试他们就无法确认问题已被定位也无法确认何时修复完成。因此尽量提前设想开发者可能会追问的问题并在描述中一次性提供这些支撑细节。两种语言的 Bug 报告范例指南给出了 Python 与 R 两个语言的真实 Bug 报告范例展示“期望行为与实际行为不符”的写法Python 范例——带时区的 timestamp 打印报错import pyarrow as pa a pa.array([0], pa.timestamp(s, tz02:00)) print(a) # 表示不正确 # 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 selfR 范例——用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) # 成功读取文件 read_csv_arrow(tf, as_data_frame TRUE) # # A tibble: 1 × 1 # x # dttm # 1 2018-10-07 20:04:05 # 此处单位是秒——不工作 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 # 此处单位是毫秒——不工作 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 # 此处单位被推断为纳秒——可以工作 read_csv_arrow( tf, col_names x, col_types ?, skip 1, as_data_frame FALSE ) # Table # 1 rows x 1 columns # $x timestamp[ns]这两个范例都遵循“给出最小复现、展示期望与实际、附带完整错误栈”的结构是新手模仿写 Bug 报告的最佳模板。识别受影响的 Arrow 组件Arrow 是一个支持多种语言、按多个组件组织的庞大项目。识别受影响的组件能让新 Issue 更快地被合适的贡献者看到组件标签Component label由 Apache Arrow 的 committer 添加用于标示 Issue 所属的项目领域例如Component: Python、Component: C标题前缀Summary prefix在 Issue 标题中用方括号加上组件名例如[Python] issue summary便于浏览未解决问题列表也让 changelog 更易读。大多数前缀与组件名完全一致但有三个例外组件Component标题前缀Summary prefixContinuous Integration[CI]Developer Tools[Dev]Documentation[Docs]Issue 生命周期从认领到关闭Issue 的两种关闭结果Bug 报告和功能请求都遵循明确的生命周期。如果一个 Issue 正在被处理应当有一位开发者被指派assigned。当 Issue 达到终态时以两种结果之一关闭Closed as completed已完成表示 Issue 已完成解决该 Issue 的 PR 应当已被 GitHub 自动关联前提是 PR 正确提及了 Issue 编号。合并 PR 时建议在被关联的 Issue 上留言说明是哪个 PR 解决了它这样 GitHub 会通知所有协作者closed as not planned不计划处理表示 Issue 被关闭、不再接收进一步更新但没有采取任何行动。过期StaleIssue 与 PR 的自动清理为保持 Issue 追踪器的可管理性长时间无活动的 Issue 和 PR 会被每日运行的 GitHub Actions 工作流自动标记为 stale。策略因类型而异类型无活动 365 天再 14 天仍无活动Pull Requests添加Status: stale-warning标签关闭 PR使用类 IssueType: usage添加Status: stale-warning标签关闭 Issue增强类 IssueType: enhancement添加Status: stale-warning标签关闭但带有Status: needs champion标签的除外其中Status: needs champion标签表示该增强功能仍被社区认可、但需要有人接手主导。防止 Issue/PR 被关闭的方法是移除Status: stale-warning标签或留言说明它仍然活跃。认领 Issue 的规则认领Assignment意味着承诺处理该 Issue。贡献者应在开始工作时自行认领——现在任何人都可以通过在评论区留言take来自行认领 Issue。这比等待维护者手动指派更加高效也与 寻找合适的首个 Issue 中的建议一致当你找到想做的 Issue 时在评论区表明兴趣并自行认领。新贡献者如何找到合适的 Issue如果你还没有想做的 Issue新贡献者指南 的 Finding good first issues 一节提供了两条捷径good-first-issue标签专为新手设计官方预计这些 Issue 最多需要两天或一个周末即可完成Status: needs champion标签社区确认仍然想要、但暂无负责人的增强请求可能比 good-first-issue 更复杂但非常适合做出有意义的贡献。找到想做的 Issue 后在评论区留言表明兴趣、必要时自行认领并记得创建新的分支再开始工作分支与 PR 生命周期详见 pr_lifecycle。如果深入代码后发现 Issue 并不像分诊者预期的那样简单也完全可以写在评论里如果对从何入手有疑问可以在 Issue 或开发邮件列表上直接提问例如“你认为$PROPOSED_APPROACH这个方案对吗”“我应该查看哪个些文件来做修改”“代码库中有没有相关的实现可以供我学习”更多推荐学习资源沟通之外社区还整理了供贡献者深入学习的概念文章与书籍汇总于 Additional information and resources 页面主要包括术语表GlossaryApache Arrow 常见术语的简短解释见 格式规范术语表GitHub ActionsArrow 通过 GitHub Actions 运行 CI/CD 工作流构建并测试每一个打开或合并的 PRNightly buildsArrow R 包的每日开发构建非官方发布版Apache Arrow releases官方发布页面GitHub 使用参考包括 fork 仓库与从 fork 创建 PR 的官方文档推荐书籍Brett Slatkin 的《Effective Python》、Bjarne Stroustrup 的《A Tour of C》第二版、Hadley Wickham 的《R Packages》与《Advanced R》等覆盖项目主要语言的学习需求。总结一份高效的 Arrow 协作清单综合 Communication 及其关联文档你在 Apache Arrow 社区高效沟通的关键动作如下提问前先搜索优先在 GitHub Issues 中搜索是否已有相同问题避免重复创建选对渠道具体问题走 GitHub Issues开放式讨论用 GitHub Discussions 或邮件列表需要广泛反馈时用邮件列表广播正确标记消息和 Issue 标题带上语言/组件标签如[C]、[Python]、[Docs]让对的人看到写清细节Bug 报告包含最小复现步骤、操作系统与 Arrow 版本、期望与实际行为、完整错误信息先沟通再动手写代码前先让开发者认可你的方案投入大量时间前先征询意见认领并推进开始工作时在 Issue 评论留言take自行认领完成后让 PR 关联 Issue保持活跃避免 Issue/PR 因长期无活动被自动标记为 stale 而关闭善用资源遇到不熟悉的语言或概念查阅 术语表 与 推荐学习资源。遵循这套沟通规范你不仅能更快得到准确的帮助也能让整个社区的协作更高效——这正是 Apache Arrow 官方新贡献者指南所要传达的核心精神。【免费下载链接】arrowApache Arrow is the universal columnar format and multi-language toolbox for fast data interchange and in-memory analytics项目地址: https://gitcode.com/GitHub_Trending/arrow3/arrow创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表