CEP 6 - 向 conda 添加频道通知

标题	向 conda 添加频道通知
状态	已接受
作者	Travis Hathaway <thathaway@anaconda.com>
创建于	2022 年 4 月 21 日
更新于	2022 年 8 月 21 日
讨论	https://github.com/conda-incubator/ceps/pull/19
实施	https://github.com/conda/conda/pull/11462

摘要

为了促进 conda 用户和频道所有者之间更好的沟通，我们希望实现一个通知功能。具体来说，此功能将使频道所有者能够向用户发送一条小消息（大约相当于一条 Twitter 帖子的大小）。此消息的显示频率将由频道所有者设置，并将为用户正在积极使用的每个频道显示（即用户 .condarc 中“channels”下的所有内容）。

消息可能包含但不限于以下用例

关于频道最新软件包添加的新闻
如何赞助、志愿或帮助特定频道
关于使用特定频道时违反 TOS 的警告
关于频道稳定性的状态更新
计划安全发布的公告

规范

规范通过问答形式在下面描述。

此消息何时显示？

通知消息将在运行以下命令时出现

create
env create
env update
install
update

此决定的理由是，上述命令都会从配置的频道检索 repodata.json。简单地添加另一个文件请求（它非常小且立即缓存）不会给这些命令的执行增加太多开销。此外，这些命令是我们的用户已经期望发生网络流量的命令，因此假设需要活动互联网连接。

以下是在运行 conda create 命令时通知消息可能出现的方式示例

$ conda create -n geopandas geopandas
Collecting package metadata (repodata.json): done
Solving environment: done

## Package Plan ##

  environment location: /Users/username/opt/conda_x86_64/envs/geopandas

  added / updated specs:
    - geopandas

... (output truncated)


Channel "defaults" has the following notices:
  [info] -- Tue May 10 11:50:34 2022
  This is a test message. It is not very long, and could have a link to a longer post:
  https://example.com/short-link

我们的用户还可以通过其他方式访问此消息吗？

此外，由于我们的用户可能希望按需查看此消息，我们将添加一个新的子命令，名为 notices。以下是一些示例，确切展示它的功能

基本用法：抓取所有当前频道的通知

$ conda notices

Retrieving notices: done

Channel "defaults" has the following notices:
  [info] -- Tue May 10 11:50:34 2022
  This is a test message. It is not very long, and could have a link to a longer post:
  https://example.com/short-link

Channel "conda-forge" has the following notices:
  [info] -- Tue May 10 11:50:34 2022
  Here is another message. It could have info about the latest happenings or blog posts from conda-forge:
  https://forge.conda.org.cn/

显示单个频道：抓取单个频道的通知

$ conda notices -c defaults

Channel "defaults" has the following notices:
  [info] -- Tue May 10 11:50:34 2022
  This is a test message. It is not very long, and could have a link to a longer post:
  https://example.com/short-link

此消息的文件格式是什么，它将包含什么？

通知消息将采用 JSON 文件格式。这将使我们不仅可以存储消息本身，还可以存储关于消息的元数据，包括关于客户端应多久显示消息一次的信息（更多内容将在下一节中介绍）。

以下是 notices.json 文件的示例，该文件将存储在频道目录结构的根目录中。

{
  "notices": [
    {
      "id": "1cd1d8e5-d96c-42d1-9c29-e8120ad80823",
      "message": "Here is an example message that will be displayed to users",
      "level": "info",
      "created_at": "2022-04-21T11:50:34+00:00",
      "expires_at": "2022-04-22T00:00:00+00:00"
    }
  ]
}

JSON 字段的详细概述

notices [数组] 包含零个或多个将显示给客户端的通知。
- id [字符串] 消息本身的唯一 ID。UUID 是首选，但没有要求的格式。
- message [字符串] 显示给用户的消息。
- level [字符串] (info|warning|critical) 之一。这些将让我们的用户知道消息的类别，并且还将允许客户端应用不同的格式规则（例如，文本颜色）。
- created_at [字符串] ISO 8601 格式的时间戳，显示消息的创建时间。
- expires_at [字符串] ISO 8601 格式的时间戳，显示消息的过期时间。

这些消息多久出现一次？

这些消息出现的频率将由频道所有者和客户端配置。这将通过 notices.json 文件本身的 expires_at 字段完成。当消息过期时，它将触发来自服务器的刷新，届时如果有新消息，它将显示新消息。

客户端将最终决定是否显示这些消息。我们将为客户端提供一个设置，以在其 .condarc 文件中永久禁用这些消息

# Zero messages will be displayed while running commands such as "install", "update", etc.
number_channel_notices: 0

动机

此 CEP 的动机来自于频道所有者（特别是 Anaconda）需要一种方式向其频道的用户广播消息。这些消息可能包含针对特定用户的特定通知（例如，通过 IP 地址识别），或者针对特定频道的更广泛受众的通用消息。

此外，这个新的通知空间还可以为我们提供一个位置，将 conda update conda 提醒重新定位到更显眼的位置（在命令输出的末尾，而不是在输出的中间）。最重要的是，其他频道可以使用这些通知作为一种方式，与他们的用户分享新闻或请求帮助维护他们的频道。

理由

为了使此功能尽可能简单并减少活动部件的数量，我们选择通过服务器上的扁平 JSON 文件提供消息。客户端负责缓存这些消息，这有助于减少它必须发出的 HTTP 请求数量。在设计这样的系统时，我们的目标是将代码复杂性保持在最低限度，同时仍然提供尽可能大的灵活性。将来，某些频道可能会选择动态提供此 JSON 文件，并且此规范允许这样做。

另一个考虑因素是将这些消息对我们的用户保持在最低限度，并允许他们轻松禁用这些消息，如果他们不想在运行“install”或“create”等命令时看到它们。虽然我们认为这些消息对于用户来说很重要，但我们也不想弄乱他们的终端输出。最终，这就是为什么我们选择默认启用此功能，但也提供了一种禁用它的方法。

向后兼容性

我们预计此新功能不会出现任何向后兼容性问题。

替代方案

在环境激活开始时显示通知：这被认为过于侵入性/烦人。
在命令输出开始时显示通知：如果放在此处，用户可能会错过，特别是对于输出量大的命令
在从存储库检索任何文件时，在 HTTP 标头中发送消息：对于某些类型的消息来说，这可能是一个更好的选择，例如下载速率限制或其他由于滥用造成的阻止，因为它可以通过 CDN 中的规则启用。但是，对于这种情况，可能最好通过一种标准方式让 conda 在控制台上显示来自 HTTP 状态代码（如 429（请求过多）和 403（禁止））的错误来解决。此外，除非存储库所有者对 Web 服务器的控制权比 Github Pages 等服务通常提供的更多，否则提供自定义标头具有挑战性。
将通知添加到 repodata.json 文件：repodata.json 文件已经被获取，因此添加一些通知将减少请求的数量。但是，repodata.json 文件已经太大了，因此它将要求客户端下载一个相当大的文件，然后才能显示通知。
创建一个包含 notices 键的通用 metadata.json 文件：这对于为其他类型的频道元数据创建空间可能很有吸引力，但为了目前保持尽可能简单，将这些内容放在它们自己的文件中更有意义。此外，如果将来有必要，它可以为对此文件的动态路由选项提供更大的灵活性。

参考

此实现类似于 npm 处理版本更新提醒的方式

npm install                                                                                                                   travishathaway@thath-work-laptop

up to date, audited 365 packages in 3s

34 packages are looking for funding
  run `npm fund` for details

5 vulnerabilities (1 moderate, 4 high)

To address all issues (including breaking changes), run:
  npm audit fix --force

Run `npm audit` for details.
npm notice
npm notice New minor version of npm available! 8.5.5 -> 8.7.0
npm notice Changelog: https://github.com/npm/cli/releases/tag/v8.7.0
npm notice Run npm install -g npm@8.7.0 to update!
npm notice

实施

完整实施的拉取请求

https://github.com/conda/conda/pull/11462

请在此拉取请求中添加任何与实施相关的改进建议。

FAQ

我多久会看到通知？

通知将按照频道所有者希望的频率显示。用户也可以完全禁用频道通知，以便在正常操作期间永远不会看到它们。

这是选择加入还是选择退出？

用户将自动选择加入此功能。他们将能够通过配置参数将其关闭。

决议

这是一个标准的、非超时的投票。

在指导委员会成员中，有 15 票“赞成”，0 票“反对”，没有弃权票。
没有荣誉指导委员会成员投票。

此投票已达到法定人数（15 + 0 = 15，至少为 21 的 60%）。

它也已通过，因为它记录了 15 票“赞成”票和 0 票“反对”票，得分为 15/15，大于 15 的 60%。

应该注意的是，在关于不使先前投票无效的次要实施细节的拉取请求中，记录了多项更改请求。作者进行了请求的更改。

版权

所有 CEP 均明确为 CC0 1.0 通用。

CEP 6 - 向 conda 添加频道通知

摘要​

规范​

此消息何时显示？​

我们的用户还可以通过其他方式访问此消息吗？​

此消息的文件格式是什么，它将包含什么？​

这些消息多久出现一次？​

动机​

理由​

向后兼容性​

替代方案​

参考​

实施​

FAQ​

我多久会看到通知？​

这是选择加入还是选择退出？​

决议​

版权​

摘要

规范