维修人员工作流程

此页供维护人员使用 — 我们中的那些将自己或其他人的变更合并到上游存储库中的人。

作为一个维护者,你完全掌握了 如何进行代码贡献 .

手动集成更改

首先,看看 astropy 存储库。中的说明 告诉git在Astropy的开发版本中从哪里寻找变更 添加对上游回购具有只读访问权限的远程。作为一名维护人员,你有读写权限。

让你的上游遥控器有一个可怕的名字是很好的,提醒你它是一个读写遥控器:

git remote add upstream-rw git@github.com:astropy/astropy.git
git fetch upstream-rw --tags

假设你有一些变化需要进入后备箱 (upstream-rw/master

更改位于您当前所在的某个分支中。例如,您正在查看某人的更改如下所示:

git remote add someone git://github.com/someone/astropy.git
git fetch someone
git branch cool-feature --track someone/cool-feature
git checkout cool-feature

所以,现在你在分支机构上,把变更合并到上游。本节的其余部分假设您属于这个分支。

几个约定

如果只有少数提交,请考虑重新定位到上游:

# Fetch upstream changes
git fetch upstream-rw

# Rebase
git rebase upstream-rw/master

请记住,如果您执行一个REBASE,并按下它,则必须手动关闭任何GitHub拉请求,因为GitHub将无法检测到更改已经合并。

一系列的承诺

如果有一系列较长的相关提交,请考虑合并::

git fetch upstream-rw
git merge --no-ff upstream-rw/master

合并将由GitHub检测,并应自动关闭任何相关的请求。

注意 --no-ff 以上。这迫使git进行一次合并提交,而不是快速前进,这样这些提交集从主干分支出来,然后用合并重新连接主历史,而不是看起来是直接在主干上进行的。

检查历史记录

现在,无论是哪种情况,您都应该检查历史是否明智,并且您有权承诺:

git log --oneline --graph
git log -p upstream-rw/master..

上面的第一行只是以一种简洁的方式显示历史,其中包含历史图形的文本表示。第二行显示提交日志,不包括可以从主干访问的提交日志。 (upstream-rw/master), and including those that can be reached from current HEAD (implied with the .. 最后)。因此,与主干相比,它显示了对这个分支唯一的提交。这个 -p 选项以补丁形式显示这些提交的差异。

推到中继线

git push upstream-rw my-new-feature:master

这推动了 my-new-feature 将此存储库中的分支转移到 master 分支在 upstream-rw 储存库。

使用里程碑和标签

这些指南改编自 similar guidelines 其次是IPython:

  • 100%确认的问题和新功能应该有一个里程碑

  • 只有以下标准才能导致问题在没有里程碑的情况下关闭:

    • 实际上不是问题(用户错误等)

    • 现有问题的副本

    • 由提供替代实现的新请求取代的请求

  • 只有在以下情况下,未决问题才应缺少里程碑:

    • 需要更多的澄清

    • 它属于哪个里程碑需要一些讨论

  • 推论:当一个问题在没有里程碑的情况下结束时,这意味着问题不会得到解决,或者根本不是一个真正的问题。

  • 一般来说,应该有以下开放的里程碑:

    • 下一个bug修复版本将针对任何仍然受支持的版本行;例如,如果0.4正在开发中,并且0.2.x和0.3.x仍然受支持,那么下一个0.2.x和0.3.x版本应该有里程碑。

    • 下一个X.Y版本,即下一个次要版本;这通常是master中所有开发的目标。

    • 下一个X.Y版本+1;例如,如果0.3是下一个版本,那么对于重要的问题,0.4也应该有一个里程碑,但是我们知道这些问题不会在下一个版本中解决。

    • 未来——这是针对所有在某个时刻需要关注但看不到立即解决方案的问题。

  • Bug修复发布里程碑应该只用于推迟在下一个次要版本中不会被修复的问题,或者对于那些不再适用于主线的先前版本。

  • 当对某个问题使用哪个里程碑有疑问时,可以使用下一个次要版本——一旦在发布之前对它进行了更仔细的审查,它总是可以移动的。

  • 与特定版本(如v0.3.0)相关联的活动里程碑应至少包含一个问题,发布标签代表发布该版本的实际任务(这也解决了GitHub的烦恼,即没有任何公开问题的里程碑会自动关闭)。

  • 需要在主线中修复,但也被确认适用于受支持的稳定版本行的问题应标记为一个或多个 'backport-*' 每个有问题的v0.X.Y分支的标签。

    • 在某些情况下,除了简单的merge-to-port错误修复程序之外,它可能需要额外的工作;如果需要这样的额外工作,那么在适当的v0.X.Y里程碑中打开“Backport-nnn-v0.X.Y”问题并不是一个坏主意。

更新和维护变更日志

阿谀奉承的“变更日志”保存在文件中 CHANGES.rst 在存储库的根目录下。正如文件扩展名所示,这是一个经过重组的文本文件。这个文件的目的是提供一个技术性的,但仍然面向用户(和开发人员)的概述,在每个公开发行版之间对Astropy做了哪些更改。这样做的目的是,它比阅读完整的git日志更切中要害,更容易理解。它列出了在版本之间添加的所有新特性,因此用户可以在添加特性时通过阅读变更日志很容易地发现。同样,它列出了所有被更改(以及如何更改)或删除的特性或api。它还列出了所有的错误修复。鼓励附属软件包维护类似的变更日志。

添加到变更日志

有两种方法可以用来向变更日志中添加新条目,每种方法都有各自的优缺点。在描述这两种方法之前应该说是具体的 all 应首先在“主”分支中添加更改日志。这是因为Astropy的每个版本都包含一个变更日志的副本,并且它应该列出Astropy以前每个版本中的所有变更。例如,当AstropyV0.3.0发布时,除了对该版本的新更改之外,changelog还应该包含到那时为止每个v0.2.x版本(及更早版本)的所有更改。

包含新功能或错误修复的变更日志条目的两种方法是:

  • 将变更日志更新包含在与变更相同的请求中。也就是说,假设这个更改是在拉请求中进行的,它可以包括一个准确的变更日志更新。

    优点:对变更日志的添加就像任何其他文档更新一样,应该是对软件进行任何原子性更改的一部分。它可以和其余的零钱一起被拉进主人。

    缺点:如果许多请求也包括变更日志更新,那么它们会很快相互冲突并需要重新调整。如果唯一的冲突在changelog中,这并不难解决,但是对于新的贡献者来说,这仍然是个麻烦。

  • 无论是通过拉请求还是其他方式,将更改合并到主更改后添加到更改日志。

    优点:基本上可以避免合并冲突问题。

    缺点:合并提交中没有“原子”地包含,这使得跟踪后端口变得更加困难。要求新的贡献者发出第二个请求,或者让具有主存储库推送访问权限的开发人员进行提交。

第一种方法可能更可取,尤其是对于核心贡献者。但后一种方法也是可以接受的。

变更日志格式

变更日志内容的确切格式目前有点松散(尽管如果我们想围绕变更日志开发更多的工具,它可能会变得更严格)。这种格式主要可以通过查看以前的版本来推断。每个版本都有自己的标题(使用 - 标题标记)以及版本和发布日期。仍在开发中的版本 (unreleased) 因为还没有发行日期。

通常最多有三个子标题(使用 ^ 标记):“新特性”、“API更改”、“错误修复”和“其他更改和添加”。后者主要是对各种变化的包罗万象,不过,如果合适的话,没有理由不增加额外的副标题。

在每个子标题下,更改通常根据它们所属的子包进行分组。适用于多个子包或仅适用于支持模块的更改,如 loggingutils 可能属于“杂项”组。

变更日志条目的实际文本通常只有一到三个句子——它们应该很容易浏览。大多数条目以方括号中的问题/请求编号结尾。

一个changelog条目也可以引用多个小的变更。例如::

- Minor documentation fixes and restructuring.
  [#935, #967, #978, #1004, #1028, #1047]

除此之外,更新变更日志的最佳建议是查看以前版本的现有条目并复制格式。