reponews 0.1.1

安装和设置

reponws需要 Python 3.7 或更高版本。只需使用Python 3 的pip（你有 pip，对吗？）来安装 reponws及其依赖项：

python3 -m pip install reponews

在第一次运行reponws之前，您需要获取一个 GitHub 个人访问令牌，以便通过 GitHub GraphQL API 获取有关您的存储库的详细信息，并且您需要创建一个配置文件，其中至少包含：

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

• 回复的电子邮件地址应将其报告发送至

• 有关如何发送这些电子邮件的详细信息

一个示例配置文件，用于向luser @example发送电子邮件。com使用sendmail命令：

[reponews]
recipient = <s>"luser@example.com"</s>
auth-token = <s>"..."</s>

[outgoing]
method = <s>"command"</s>
command = [<s>"sendmail"</s>, <s>"-i"</s>, <s>"-t"</s>]

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

例子

reponws可能会发送给您的电子邮件示例：

[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>]

reponws命令查询 GitHub 的 GraphQL API 以查找其配置文件中指定的存储库（默认情况下，所有与经过身份验证的用户关联的存储库）上的新问题、拉取请求、讨论、发布、标签、stargazers 和/或分叉，并编写和发送按时间顺序列出事件的电子邮件。报告中还包括有关新跟踪和未跟踪的存储库以及重命名的存储库的通知。如果没有新活动，则不发送电子邮件。

在一般情况下，“新”活动是自上次成功运行reponws以来发生的任何事情（特别是自上次更新状态文件以来）。第一次运行reponws时，它只报告它现在正在跟踪的所有存储库。如果reponws停止跟踪存储库（通常是因为配置文件中的存储库列表已被编辑）然后再次开始跟踪它，它将不会从中断的地方继续；相反，当它第一次开始再次跟踪存储库时，它会及时标记那个时间点，然后只报告它之后发生的事件。如果repones会发生类似的行为停止跟踪某种类型的活动，然后再次开始跟踪它。

配置

reponws是通过一个TOML文件配置的，该文件的默认位置取决于您的操作系统：

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

收件人电子邮件地址

[未给出--print-body时需要] reponnews应将其报告发送到的电子邮件地址 。这可以是简单的电子邮件地址（例如，“me@example.com”）或带有尖括号地址的显示名称（例如，“Madam E <me@example.com>”）。请注意，如果显示名称包含任何标点符号，则需要将其括在双引号中，然后需要对其进行转义以便在 TOML 字符串中使用，例如 "\"Joe Q. Recipient\" <jqr@example.net >”。

发件人电子邮件地址

发件人：在reponws的电子邮件中添加的地址；指定方式与接收者相同。如果未指定sender，则假定电子邮件发送机制将自动填写From: 地址。

主题字符串

申请回复邮件的主题；默认为“[reponews] GitHub 存储库上的新活动”。

授权令牌字符串

用于与 GitHub API 交互的 GitHub OAuth 令牌/个人访问令牌。如果auth-token未设置，则从auth-token-file指定的文件中读取令牌；如果也没有设置，则将按顺序查询环境变量GITHUB_TOKEN和GH_TOKEN以获得令牌。环境变量可以直接在环境中设置，也可以从.env文件中读取（参见 上面“选项”下的--env选项）。

授权令牌文件路径

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

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

状态文件路径

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

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

Linux	~/.local/state/reponews/state.json 或$XDG_STATE_HOME/reponews/state.json
苹果系统	〜/图书馆/应用程序支持/reponews/state.json
视窗	C:\Users\<用户名>\AppData\Local\jwodder\reponews\state.json

api-url网址

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

活动表

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

问题布尔值

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

拉取请求布尔值

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

讨论布尔值

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

发布布尔值

是否在跟踪的存储库中报告新版本；默认为真

标签布尔值

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

发布标签布尔值

此设置控制在跟踪标签和版本时如何处理也制作为版本的标签。如果为真，则此类标签将与发布分开报告。如果为 false（默认值），则不报告此类标签。

星星布尔值

是否为跟踪的存储库报告新的观星者；默认为真

叉布尔值

是否报告跟踪存储库的新分支；默认为真

我的活动布尔

如果为 false（默认值），则不会报告经过身份验证的用户执行的活动。

附属表

一个子表，描述要获取和跟踪与经过身份验证的用户关联的存储库的哪些类型的存储库活动。该表的键与[reponews.activity]的布尔键相同 。

回购表

一个子表，描述要为特定存储库或属于给定用户/组织的存储库获取和跟踪哪些类型的存储库活动。子表的键必须是 “所有者/名称”（对于特定存储库）或“所有者/*”（对于属于给定用户/组织的所有存储库）的形式，并且值必须是具有相同布尔值的子表键为 [reponnews.activity]。

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

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

1. [reponews.activity.repo.“所有者/名称”]

2. [reponews.activity.repo.“所有者/*”]

3. [reponews.activity.affiliated]（如果存储库隶属于经过身份验证的用户）

4. [reponnews.activity]

回购表

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

隶属关系字符串列表

存储库从属关系列表，描述与经过身份验证的用户关联的存储库应该被自动跟踪。隶属关系是“OWNER”（用于跟踪用户拥有的存储库）、“ORGANIZATION_MEMBER”（用于跟踪属于用户所属组织的存储库）和 “COLLABORATOR”（用于跟踪用户所在的存储库）添加为合作者）。未知的从属关系会导致错误。如果未指定从属关系，则默认为所有从属关系类型。

包括字符串列表

除了附属存储库之外要跟踪的存储库列表。存储库可以指定为“所有者/名称”（针对特定存储库）或“所有者/*”（针对属于给定用户/组织的所有存储库）。

排除字符串列表

要从跟踪中排除的存储库列表，指定方式与include相同。此选项优先于 从属关系并包含设置。

[reponews]
recipient = <s>"luser@example.com"</s>

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

# Fetch the GitHub OAuth token from the "token.txt" file next to the config
# file:
auth-token-file = <s>"token.txt"</s>

state-file = <s>"~/.cache/reponews.json"</s>

[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 = [<s>"OWNER"</s>, <s>"ORGANIZATION_MEMBER"</s>]
include = [
    <s>"pypa/packaging"</s>,
    <s>"pypa/pip"</s>,
    <s>"pypa/setuptools"</s>,
    <s>"some-user/*"</s>,
]
exclude = [
    <s>"some-user/boring-repo"</s>,
]

发送电子邮件

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