reponews 0.5.0

安装和设置

reponews 需要 Python 3.8 或更高版本。只需使用 pip 为 Python 3 安装 reponews 及其依赖项

python3 -m pip install reponews

在首次运行 reponews 前，您需要通过 GitHub GraphQL API 获取您仓库的详细信息，为此您需要 创建一个 GitHub 个人访问令牌，并且需要创建一个配置文件，至少包含以下内容：

• 访问令牌或包含该令牌的文件路径

• reponews 应发送报告的电子邮件地址

• 发送电子邮件的详细信息

一个示例配置文件，用于通过 sendmail 命令将电子邮件发送到 luser@example.com

[reponews]
recipient = "luser@example.com"
auth-token = "..."

[outgoing]
method = "command"
command = ["sendmail", "-i", "-t"]

有关详细信息，请参阅下方的“配置”。

示例

这是一个 reponews 可能发送给您的电子邮件示例

[luser/my-repo] ISSUE #42: I found a bug (@bug-finder)
<https://github.com/luser/my-repo/issues/42>

@bug-fixer forked luser/my-repo
<https://github.com/bug.fixer/my-repo>

[luser/my-repo] PR #43: I fixed that bug (@bug-fixer)
<https://github.com/luser/my-repo/pull/43>

★ @repo-fan starred orgcorp/bigrepo

[orgcorp/bigrepo] DISCUSSION #123: How do I use this? (@confused-user)
<https://github.com/orgcorp/bigrepo/discussions/123>

[theteam/theproject] RELEASE v1.0a1 [prerelease]: v1 Preview (@github-actions[bot])
<https://github.com/theteam/theproject/releases/tag/v1.0a1>
> We're gearing up for the first full release!  Here are some changes you'll find:
>
> * Added a feature
> * Fixed a bug

Now tracking repository luser/brand-new-repo
<https://github.com/luser/brand-new-repo>
> This is the repository description.

No longer tracking repository tmprepos/deleted-repo

Repository renamed: team-member/new-project → theteam/new-project

用法

reponews [<options>]

reponews 命令通过 GitHub 的 GraphQL API 查询配置文件中指定的仓库（默认情况下为认证用户关联的所有仓库）上的新问题、拉取请求、讨论、发布、标签、星标和/或分支，并按时间顺序排列事件，并发送包含这些事件的电子邮件。报告中还包括有关新跟踪和未跟踪的仓库以及重命名的仓库的通知。如果没有新的活动，则不会发送电子邮件。

一般情况下，“新”活动是指自上次 reponews 成功运行以来发生的事情（具体来说，是自最后更新状态文件以来）。首次运行 reponews 时，它只会报告它现在正在跟踪的所有仓库。如果 reponews 停止跟踪一个仓库（通常是因为配置文件中的仓库列表被编辑），然后再次开始跟踪它，它将 不会 从上次停止的地方继续；相反，当它再次开始跟踪仓库时，它会标记那个时间点，之后只会报告该时间点之后的事件。如果 reponews 停止跟踪某种类型的活动然后再次跟踪它，也会出现类似的行为。

配置

“reponews”配置通过一个TOML文件，其默认位置取决于您的操作系统。

此TOML文件必须包含一个带有以下键和子表的[reponews]表（除非另有说明，所有这些都是可选的）。未知键会导致错误。

recipient电子邮件地址

当未提供--print-body时为必填项。这是reponews应发送报告的电子邮件地址。这可以是纯电子邮件地址（例如，"me@example.com"）或带有尖括号地址的显示名称（例如，"Madam E <me@example.com>"）。请注意，如果显示名称包含任何标点符号，则必须将其括在双引号中，然后需要在TOML字符串中使用转义字符，例如："\"Joe Q. Recipient\" <jqr@example.net>"。

sender电子邮件地址

这是reponews电子邮件中的From:地址；与recipient的指定方式相同。如果没有指定sender，则假定电子邮件发送机制会自动适当地填写From:地址。

subject字符串

应用于reponews电子邮件的主题；默认为“[reponews]您的GitHub仓库的新活动”。

auth-token字符串

用于与GitHub API交互的GitHub访问令牌。如果未设置auth-token，则将从指定的auth-token-file文件中读取令牌。如果两个键都没有设置，则GitHub令牌将通过以下顺序查找

• 环境变量GH_TOKEN和GITHUB_TOKEN（可能通过.env文件设置；参见上面“选项”下的--env选项）

• 如果已安装，则gh命令

• hub命令的配置文件

• Git配置选项hub.oauthtoken

auth-token-file路径

包含用于与GitHub API交互的GitHub访问令牌的文件的路径。文件必须仅包含令牌以及可能的前导和/或尾随空格。

路径可以以波浪线(~)开头，以指示用户主目录中的文件。相对路径将相对于包含配置文件的目录解析。

state-file路径

reponews将存储仓库活动状态的文件的路径，用于确定新活动的截止点。路径可以以波浪线(~)开头，以指示用户主目录中的文件。相对路径将相对于包含配置文件的目录解析。

状态文件的默认位置取决于您的操作系统

Linux	~/.local/state/reponews/state.json 或 $XDG_STATE_HOME/reponews/state.json
macOS	~/Library/Application Support/reponews/state.json
Windows	%USERPROFILE%\AppData\Local\jwodder\reponews\state.json

api-urlURL

要查询的GraphQL端点；默认为“https://api.github.com/graphql”

活动表格

描述要获取和跟踪的存储库活动类型的子表。此表格可能包含以下键

issues布尔值

是否报告跟踪存储库中的新问题；默认为true

pull-requests布尔值

是否报告跟踪存储库中的新拉取请求；默认为true

discussions布尔值

是否报告跟踪存储库中的新讨论；默认为true

releases布尔值

是否报告跟踪存储库中的新发布；默认为true

prereleases布尔值

是否报告跟踪存储库中的新预发布；默认为true。此设置仅在releases为true时生效。

drafts布尔值

是否报告跟踪存储库中的新草案发布；默认为true。此设置仅在releases为true时生效。

注意，如果reponews在处于草稿状态时看到一个发布（即使草稿没有报告），然后在后续运行中该发布已发布，则在后续运行中不会报告该发布，无论drafts的值如何。

tags布尔值

是否报告跟踪存储库中的新标签；默认为true

released-tags布尔值

此设置控制处理同时跟踪标签和发布时的情况。如果为true，则此类标签将单独从发布中报告。如果为false（默认），则不报告此类标签。

stars布尔值

是否报告跟踪存储库中的新星标；默认为true

forks布尔值

是否报告跟踪存储库中的新分叉；默认为true

my-activity布尔值

当为false（默认）时，不会报告认证用户执行的活动。

affiliated表格

描述为认证用户关联的存储库获取和跟踪活动类型的子表。表格的键与[reponews.activity]的布尔键相同。

repo表格

描述为特定存储库或属于特定用户/组织的存储库获取和跟踪活动类型的子表。子表的键必须为"owner/name"（对于特定存储库）或"owner/*"（对于属于给定用户/组织的所有存储库），并且值必须是具有与[reponews.activity]相同的布尔键的子表。

默认情况下，所有在[reponews.activity.repo]中作为键列出的存储库和存储库所有者将由reponews跟踪，就像它们在reponews.repos.include下列出一样（见下文）。可以通过在键的子表中设置include = false来禁用单个键。

在确定要获取和跟踪的存储库活动时，将按以下顺序在相关表中查找每个设置，从优先级最高到最低

1. [reponews.activity.repo."owner/name"]

2. [reponews.activity.repo."owner/*"]

3. [reponews.activity.affiliated]（如果存储库与认证用户关联）

4. [reponews.activity]

repos表格

描述要跟踪的存储库的子表。此表可能包含以下键

affiliations字符串列表

一个字符串列表，描述与认证用户关联的存储库应该如何自动跟踪。关联可以是"OWNER"（用于跟踪用户拥有的存储库），"ORGANIZATION_MEMBER"（用于跟踪用户所属组织的存储库），以及"COLLABORATOR"（用于跟踪用户被添加为协作者的存储库）。未知关联将导致错误。当未指定affiliations时，它默认为所有关联类型。

include字符串列表

一个要跟踪的存储库列表，包括关联的存储库。存储库可以指定为"owner/name"（特定存储库）或"owner/*"（属于特定用户/组织的所有存储库）。

exclude字符串列表

一个要排除在跟踪之外的存储库列表，指定方式与include相同。此选项优于affiliations和include设置。

[reponews]
recipient = "luser@example.com"

sender = "RepoNews Bot <reponews@example.net>"

# Fetch the GitHub access token from the "token.txt" file next to the
# config file:
auth-token-file = "token.txt"

state-file = "~/.cache/reponews.json"

[reponews.activity]
# Don't report new issues or tags:
issues = false
tags = false

[reponews.activity.affiliated]
# Do report new issues for affiliated repositories:
issues = true

[reponews.activity.repo."pypa/*"]
# Don't report forks of pypa/* repositories:
forks = false
# Don't track all pypa/* repositories; only track those we're affiliated
# with and those listed under `reponews.repos.include`.
#
# Without this setting, the presence of `[reponews.activity.repo."pypa/*"]`
# would cause reponews to track all repositories belonging to the pypa
# organization.
include = false

[reponews.repos]
affiliations = ["OWNER", "ORGANIZATION_MEMBER"]
include = [
    "pypa/packaging",
    "pypa/pip",
    "pypa/setuptools",
    "some-user/*",
]
exclude = [
    "some-user/boring-repo",
]

发送电子邮件

reponews使用outgoing发送电子邮件，允许它处理多种发送方法，如sendmail、SMTP等。可以在reponews配置文件（作为[outgoing]表格）或outgoing的默认配置文件中找到outgoing配置。有关更多信息，请参阅outgoing文档。