changelist

一个自动化发布说明生成的工具。

例如，请参阅 https://github.com/scientific-python/changelist/blob/main/CHANGELOG.md。

功能

• 编译两个给定git提交之间的拉取请求、代码作者和审查者的列表。
• 根据GitHub标签将拉取请求分类到不同的部分。
• 用更详细的总结覆盖拉取请求的标题。
• 在拉取请求的单独总结中记录无关的变化。

此项目目前处于alpha阶段，可能不完整或有很多变化！

安装

pip install changelist

使用

该脚本需要一个 GitHub个人访问令牌。该令牌不需要任何权限，因为它仅用于增加查询限制。

export GH_TOKEN='...'
changelist scientific-python/changelist v0.2.0 main

这将列出所有拉取请求、作者和审查者，它们在v0.2.0和main（不包括v0.2.0）之间的提交中进行了操作。根据tool.changelist.label_section_map中的配置，将拉取请求分类到不同的部分。

编写拉取请求摘要

默认情况下，changelist将回退到拉取请求的标题及其GitHub标签，以将其分类到适当的部分。但是，如果您想要更长的更改摘要，您可以在拉取请求描述的任何位置添加以下形式的代码块：

```release-note
An ideally expressive description of the change that is included as
a single bullet point. Newlines are removed.
```

有时，拉取请求会引入多个更改，这些更改应该列在不同的部分中。因此，可以多次使用类似上面的摘要块。此外，您可以通过在摘要中添加 {label="..."} 来为每个摘要添加独立的标签。这些标签的排序方式与常规拉取请求标签相同。例如，下面的两个摘要将进入不同的部分。

```release-note {label="Bug fix"}
Make `is_odd()` work for negative numbers.
```

```release-note
Deprecate `ìs_odd`; use `not (x % 2)` instead! {label="API, Highlight"}
```

配置

changelist 可以从两个来源进行配置，优先级顺序如下

• 指定 --config 选项的本地 TOML 文件
• 在 stop_rev 位置的远程 pyproject.toml

如果上述文件中未指定配置选项，changelist 将回退到以下配置

# Default changelist configuration as supported in pyproject.toml
[tool.changelist]

# A template string that is included as the title of the generated notes.
# "{repo_name}" and "{version}", if given, are replaced by the respective
# values given in the command line.
title_template = "{repo_name} {version}"

# A template string that is included as introductory text after the title.
# "{repo_name}" and "{version}", if given, are replaced by the respective
# values given in the command line.
intro_template = """
We're happy to announce the release of {repo_name} {version}!
"""

# A template string that is included at the end of the generated notes.
# "{repo_name}" and "{version}", if given, are replaced by the respective
# values given in the command line.
outro_template = """
_These lists are automatically generated, and may not be complete or may contain
duplicates._
"""

# Profiles that are excluded from the contributor list.
ignored_user_logins = [
    "web-flow",
]

# If this regex matches a pull requests description, the captured content
# is included instead of the pull request title. E.g. the
# default regex below is matched by
#
# ```release-note
# An ideally expressive description of the change that is included as
# a single bullet point. Newlines are removed.
# ```
#
# If you modify this regex, make sure to match the content with a capture
# group named "summary". The regex is allowed to match more than once in which
# case a single pull request may result in multiple items (see
# `pr_summary_label_regex` for why that might be useful).
pr_summary_regex = "^```release-note\\s*(?P<summary>[\\s\\S]*?\\w[\\s\\S]*?)\\s*^```"

# Sometimes pull requests introduce changes that should be listed in different
# sections. For that reason, `pr_summary_regex` can match more than once and
# this regex, `pr_summary_label_regex`, can be used to add independent labels
# to each summary. These labels are sorted with the `label_section_map` the
# same way as regular pull request labels are. E.g. the example below will both
# match and go into separate sections:
#
# ```release-note {label="Bug fix"}
# Make `is_odd()` work for negative numbers.
# ```
#
# ```release-note
# Deprecate `ìs_odd`; use `not (x % 2)` instead! {label="API, Highlight"}
# ```
#
# If you modify this regex, make sure to match the content with a capture
# group named "label".
pr_summary_label_regex = """{[^}]*?label=[\\"](?P<label>[^\\"]+)[^}]*?}"""

# If any of a pull request's labels matches one of the regexes on the left side
# its summary will appear in the appropriate section with the title given on
# the right side. If a pull request doesn't match one of these categories it is
# sorted into a section titled "Other". Pull request can appear in multiple
# sections as long as their labels match.
[tool.changelist.label_section_map]
".*Highlight.*" = "Highlights"
".*New feature.*" = "New Features"
".*API.*" = "API Changes"
".*Enhancement.*" = "Enhancements"
".*Performance.*" = "Performance"
".*Bug fix.*" = "Bug Fixes"
".*Documentation.*" = "Documentation"
".*Infrastructure.*" = "Infrastructure"
".*Maintenance.*" = "Maintenance"

设置您的仓库

要使用默认配置将合并的 PR 分类到 changelist 中，每个 PR 必须有一个与 label_section_map 表左侧的正则表达式匹配的标签，例如 type: Highlights。

标签检查

您可能希望确保每个 PR 都有一个关联的 type: 标签，我们建议添加一个动作，如果缺少标签则使 CI 失败。

为此，将以下内容放置在 .github/workflows/label-check.yaml

name: Labels

on:
  pull_request:
    types:
      - opened
      - reopened
      - labeled
      - unlabeled
      - synchronize

env:
  LABELS: ${{ join( github.event.pull_request.labels.*.name, ' ' ) }}

jobs:
  check-type-label:
    name: ensure type label
    runs-on: ubuntu-latest
    steps:
      - if: "contains( env.LABELS, 'type: ' ) == false"
        run: exit 1

里程碑

通常，具有反映实际已合并 PR 的里程碑是有帮助的。因此，我们建议添加一个动作，将下一个打开的里程碑附加到任何已合并的 PR 上。

为此，将以下内容放置在 .github/workflows/milestone-merged-prs.yaml

name: Milestone

on:
  pull_request_target:
    types:
      - closed
    branches:
      - "main"

jobs:
  milestone_pr:
    name: attach to PR
    runs-on: ubuntu-latest
    steps:
      - uses: scientific-python/attach-next-milestone-action@bc07be829f693829263e57d5e8489f4e57d3d420
        with:
          token: ${{ secrets.MILESTONE_LABELER_TOKEN }}
          force: true

有关更多信息，请参阅 https://github.com/scientific-python/attach-next-milestone-action