大Pandas的保养#
这本指南是为大Pandas的养育者准备的。对于希望了解大Pandas的发展过程以及成为养育者需要哪些步骤的贡献者来说,这也可能是有趣的。
主要投稿指南可在 为Pandas做贡献 。
角色#
Pandas使用两个级别的权限: 分诊 和 core 团队成员。
分诊成员可以标记和关闭问题并拉回请求。
核心团队成员可以标记和关闭问题和拉入请求,并可以合并拉入请求。
GitHub发布完整的 list of permissions 。
任务#
Pandas在很大程度上是一个志愿者项目,所以这些任务不应该被解读为对分类和维护人员的“期望”。相反,它们是对作为维护员意味着什么的一般性描述。
对新归档问题进行分类(请参见 问题分类 )
审核新打开的拉取请求
响应现有问题的更新并拉入请求
推动对搁置问题和拉回请求的讨论和决定
在API设计问题上提供经验/智慧,以确保一致性和可维护性
项目组织(主持/参加开发人员会议,代表Pandas)
https://matthewrocklin.com/blog/2019/05/18/maintainer may be interesting background reading.
问题分类#
以下是对新打开的问题进行分类的典型工作流程。
感谢记者开设一期
问题跟踪器是许多人与Pandas项目本身的第一次互动,而不仅仅是使用类库。因此,我们希望这是一次受欢迎的、愉快的体验。
是否提供了必要的信息?
理想情况下,记者会填写问题模板,但许多人并不这样做。如果缺少关键信息(比如他们使用的Pandas版本),请随意询问,并在问题上贴上“需要信息”的标签。报告应遵循中的指导方针 错误报告和增强请求 。如果他们没有遵循模板,您可能想要链接到它。
确保标题准确地反映了问题。如果不清楚,请自己编辑。
这是一个重复的问题吗?
我们有许多悬而未决的问题。如果新问题明显是重复的,则将新问题标记为“重复的”,分配里程碑“无操作”,并使用指向原始问题的链接关闭该问题。确保仍然感谢记者,并鼓励他们在最初的问题上插话,也许还会尝试解决它。
如果新问题提供了相关信息,例如更好或略有不同的示例,则将其作为对原始帖子的评论或编辑添加到原始问题中。
该问题是否最小且可重现 ?
对于错误报告,我们要求记者提供一个最小的可重现的例子。有关这一问题的详细解释,请参阅https://matthewrocklin.com/blog/work/2018/02/28/minimal-bug-reports。如果该示例不可重现,或者如果它是 显然 不是最低限度的,请随时询问记者是否可以提供并举例或简化提供的一个。一定要承认,写出最少的可重现的例子是一项艰苦的工作。如果记者正在苦苦挣扎,你可以试着自己写一篇,我们会编辑原始帖子,将其包括在内。
如果不能提供可复制的示例,则添加“需要信息”标签。
如果提供了一个可复制的示例,但您看到的是简化,请用您更简单的可复制示例编辑原始帖子。
这是一个明确定义的功能请求吗?
一般来说,Pandas更喜欢在提出拉请求之前讨论和设计问题中的新功能。鼓励提交者包括新功能的建议API。让他们编写完整的文档字符串是确定细节的好方法。
在决定这项提议是否适用于大Pandas之前,我们需要几位大Pandas饲养者的讨论。
这是一个用法问题吗?
我们更喜欢在StackOverflow上询问带有Pandas标签的用法问题。Https://stackoverflow.com/questions/tagged/pandas
如果这个问题很容易回答,请随时链接到相关文档部分,让他们知道将来应该在StackOverflow上出现此类问题,并结束该问题。
我应该加上什么标签和里程碑?
贴上相关标签。这是一门艺术,需要经验。看看类似的问题,就能感受到事物是如何被贴上标签的。
如果问题定义明确,并且修复方法似乎相对简单,则将该问题标记为“良好的第一个问题”。
通常,新的问题将被分配到“贡献欢迎”里程碑,除非它知道这个问题应该在特定的版本中解决(比方说,因为它是一个大的回归)。
结束期#
这里要小心:许多人将结束一个问题解释为我们在说对话结束了。通常情况下,最好是给记者一些时间来响应或自行关闭他们的问题,如果确定该行为不是错误,或者功能超出了范围。有时记者会走开,我们会在谈话结束后结束这一问题。
审查拉式请求#
任何人都可以查看Pull请求:常规贡献者、分级者或核心团队成员。但只有核心团队成员可以在准备好后合并拉请求。
以下是在审核拉式请求时需要检查的一些事项。
测试应该放在一个合理的位置:与密切相关的测试放在同一个文件中。
新的公共API应该包含在
doc/source/reference/
。新的/更改的API应使用
versionadded
或versionchanged
指令。面向用户的更改应该在相应的文件中包含Whatsnew。
回归测试应该引用原始的GitHub问题号,如下所示
# GH-1234
。Pull请求应该被标记并分配适当的里程碑(用于回归修复和小错误修复的下一个补丁版本,否则是下一个次要里程碑)
更改应符合我们的 版本策略 。
回溯#
如果要将更改从较新的分支应用到稳定分支,则可以注释::
@meeseeksdev backport version-branch
这将触发一个工作流,该工作流会将给定的更改支持到一个分支(例如@meeseeksdev Backport 1.2.x)
清理旧问题#
Pandas身上的每一个公开问题都是有代价的。悬而未决的问题使寻找重复的Pandas变得更加困难,也可能使人们更难知道需要对Pandas做什么。也就是说,解决问题本身并不是一个目标。我们的目标是让Pandas尽其所能,而这最好是通过确保我们公开发行的问题的高质量来实现。
有时,错误会被修复,但问题不会链接到拉请求中。在这些情况下,注释为“此问题已修复,但可以使用测试”。并将问题归类为“好的第一个问题”和“需要检验”。
如果一个较旧的问题没有遵循我们的问题模板,请编辑原始帖子,包括一个最小的示例、实际输出和预期输出。问题报告的一致性是有价值的。
如果一个较旧的问题缺少可复制的示例,请将其标记为“需要信息”,并要求他们提供一个(如果可能,也可以自己编写一个)。如果没有合理地尽快提供,请根据中的政策关闭 结束期 。
正在清理旧的拉取请求#
有时,贡献者无法完成拉取请求。如果距离上一次请求更改的审查已经过去了一段时间(比如两周),请温和地询问他们是否仍有兴趣进行这项工作。如果又过去了两周左右,没有任何回应,请感谢他们的工作,并关闭拉回请求。评论最初的问题,“在#1234有一个停滞不前的公关,这可能是有帮助的。”如果公关相对接近被接受,也许可以将这个问题标记为“好的第一个问题”。
此外,核心团队成员可以推送到贡献者分支。这可能有助于将重要的公关推过界线,或修复小的合并冲突。
成为大Pandas的养育者#
完整的过程在我们的 governance documents 。总而言之,我们很乐意为任何对问题跟踪器有帮助而表现出兴趣的人提供分类许可。
核心团队成员的最新名单在https://github.com/pandas-dev/pandas-governance/blob/master/people.md
合并拉式请求#
只有核心团队成员可以合并拉式请求。我们有一些指导方针。
您通常不应自行合并您自己的拉入请求。例外包括修复配置项的小更改(例如,固定包版本)。
您不应合并具有活动讨论的拉入请求,也不应合并具有
-1
来自核心维护人员的投票。大Pandas的运作方式是一致的。对于较大的变更,最好至少有两个核心团队成员的+1。
除了中列出的项目外 结束期 ,您应该验证是否为Pull请求分配了正确的里程碑。
与补丁发布里程碑合并的拉取请求通常将由我们的机器人回传。确认机器人注意到了合并(它通常会在一分钟内留下评论)。如果需要手动后端,请这样做,并在手动完成后删除“需要后端”标签。如果您忘记在标记之前分配里程碑,您可以请求机器人使用以下命令来支持它:
@Meeseeksdev backport <branch>