获取 Gentoo！

GLEP 42：关键新闻报道

作者 Ciaran McCreesh <[email protected]>，Stephen Bennett <[email protected]>，Zac Medico <[email protected]>，Ulrich Müller <[email protected]>
类型 标准跟踪
状态 最终
版本 4
创建日期 2005-10-31
上次修改日期 2023-02-22
发布历史 2005-11-01, 2005-11-05, 2005-11-07, 2005-12-11, 2005-12-13, 2005-12-18, 2006-01-05, 2006-03-02, 2006-03-06, 2006-06-12, 2006-09-05, 2016-03-10, 2017-11-27
GLEP 源代码 glep-0042.rst

摘要

本 GLEP 提出了一种新的方法，用于通知用户有关树相关的重要的更新和新闻。

动机

尽管大多数软件包更新都很干净，并且需要很少的用户操作，但偶尔升级需要用户干预。最近的例子包括gcc-3.4在x86上的稳定化以及mysql-4.1数据库格式的更改。

目前有几种方法可以将重要的新闻项目传递给我们的用户，但没有一种特别有效

  • Gentoo 每周新闻
  • 以下gentoo-announce, gentoo-user和gentoo-dev邮件列表
  • Gentoo 论坛
  • Gentoo 主网站
  • Gentoo 新闻的 RSS 订阅
  • einfo和ewarn消息在pkg_setup或pkg_postinst

中需要一种更可靠的方法来向用户发布关键更新的新闻，以避免重复各种先前的升级灾难。本 GLEP 提出了一种基于通过rsync

树向用户推送新闻项目的解决方案。

重要einfo本 GLEP 并非旨在替换或修改安装后显示的消息。这是一个单独的问题，由elog [2].

需求

处理。

一个足够的解决方案必须满足以下所有要求
先发制人
在系统出现故障 *之前* 应告知用户更改，而不是在损坏已经发生之后。理想情况下，系统管理员将获得充足的预警来计划困难的升级和更改，而不是仅在采取行动之前才被告知。
无需用户订阅gentoo-announce已经证明 [6] 许多用户不阅读邮件列表或RSS
订阅。需要订阅的解决方案与当前方法相比没有任何优势。
无需用户监控
已经证明 [6] 许多用户不阅读发布到 Gentoo 网站的新闻项目，或者直到为时已晚才阅读新闻项目。依赖于主动监控特定来源的解决方案与当前方法相比没有任何优势。
相关性
不使用特定软件包的系统管理员不必阅读仅影响该软件包的新闻项目。某些新闻项目可能与大多数或所有用户相关，但那些不相关的项目不应强制用户阅读。
轻量级
期望所有用户在其系统上都具有 MTA、Web 浏览器、电子邮件客户端、cron 守护程序或文本处理套件是不合理的。用户不应被迫安装不合理的额外软件才能阅读新闻项目。
无隐私侵犯
使用该解决方案的用户不应被要求提供有关其系统的信息（例如，IP 地址或已安装的软件包）。
支持多种交付方式

某些用户可能希望通过电子邮件查看新闻项目，某些用户可能希望通过终端查看，而某些用户可能希望通过 Web 浏览器查看。解决方案应该支持所有这些方法，或者（更理想的是）使编写以不同方式显示新闻项目的客户端变得简单。

以下特性将是理想的
可国际化
能够提供多种语言的消息可能是有益的。
质量控制
应该有一些方法来确保不会发送措辞不当或不相关的消息，例如由经验不足的开发人员或英语技能不佳的开发人员发送的消息。
对开发人员简单
发布新闻项目应该尽可能地简单。
对用户简单
阅读相关的新闻项目应该尽可能地简单。
与现有和未来的新闻来源兼容

规范

概述

新闻系统理想情况下能够轻松地与现有的新闻来源（例如，论坛、GWN、Gentoo 主网站）集成，而不会遇到过多的困难。类似地，不应排除与任何未来的新闻来源的轻松互操作性。

  1. 新闻项目的发布和传递给用户的方式如下
  2. 编写新闻项目。使用的格式将在下面描述。
  3. 根据 新闻项目质量控制 中描述的过程审查新闻项目。
  4. 将新闻项目提交到 VCS 存储库。从这里，它将与 rsync 树合并。这在 新闻项目分发 中进行了描述。
  5. 用户在同步时获取新闻项目。这确保了在用户意外进行不必要的更改之前将相关的新闻项目推送到用户。本 GLEP 不需要对现有的 rsync 过程进行任何更改。
  6. 包管理器过滤新闻项目，如果相关，则标记新闻项目以供阅读。包管理器还应显示一条通知，告知用户有未读的新闻项目。

所需的 Portage 增强功能

新闻项目由用户选择的新闻项目阅读器处理。请参阅 新闻项目客户端。

  • 需要对 Portage 进行以下扩展每个存储库（包括覆盖层）都需要一个唯一的标识符。假设标识符将是一个由以下字符组成的字符串：a到, zaA, 0a9, +Z-（加号），_（连字符）
  • （下划线）。Portage 必须提供一种方法，让外部程序获取给定系统所有存储库标识符的列表。假设这将采用portageq命令的形式（例如，).
  • portageq get_repo_idsPortage 必须提供一种方法，让外部程序获取给定系统所有存储库标识符的列表。假设这将采用portageqPortage 必须提供一种方法，让外部程序获取具有给定 ID 的存储库的基本路径。假设这将采用).
  • portageq get_repo_root gentoo-x86Portage 必须扩展portageq has_version
  • portageq get_repo_root gentoo-x86Portage 必须提供一种方法，让外部程序获取给定系统所有存储库标识符的列表。假设这将采用以支持对给定存储库 ID 的限制。以实现一个命令，该命令返回是否为给定存储库 ID 使用的配置文件与给定配置文件完全相同（例如，).

portageq profile_used default-linux/sparc/sparc64/2004.3 gentoo-x86

新闻项目标识

在以下规范中假定这些扩展。每个新闻项目都将有一个唯一的标识符。此标识符将采用以下形式：yyyy-mm-dd-short-name，其中yyyy2005), 是年份（例如，mm01是月份（12到01是月份（31）和 dd 是月份中的日期（）。该short-name是一个非常简短的名称，用于描述新闻项目（例如，yoursql-updates），仅由以下字符组成：, 0-9, +Z-a-z_（连字符）和）。该（下划线）。虽然对

新闻项目目录

的长度没有严格的限制，但强烈建议将其限制在 20 个字符以内。

每个新闻项目都将由一个目录表示，其名称与新闻项目的标识符相同。该目录将包含一个名为yyyy-mm-dd-short-name.en.txt

的文件，其中包含新闻项目的英文文本，格式如下所述。新闻项目的任何翻译都将提供在其他文件中。其名称yyyy-mm-dd-short-name.lang.txt是通过将en

新闻项目文件

替换为另一个 IETF 语言标签 [1] 从原始文件名获得的。但是，只有新闻项目的英文版本才是权威的。这种以英语为中心的做法是基于先例 [9]。

新闻项目文件是一个文本文件，使用 UTF-8 [14] 编码，以与现有的 Gentoo 文档 [3] 和树 [8] 兼容，并出于相同的原因。

新闻项目文件的内容将包含一个 RFC 822 样式的标题 [13]，然后是纯文本格式的消息主体。本 GLEP 定义了各种可选和强制标题。未来的 GLEP 可能会提出新的标题——处理这些新闻项目的工具必须忽略任何无法识别的标题。

注意

新闻项目标题

本 GLEP 的先前版本要求新闻项目必须使用分离的 OpenPGP 签名进行签名。在将新闻项目移动到具有提交签名的 Git 存储库以及根据 GLEP 74 [11] 部署完整树验证后，不再认为此操作是必要的。

以下标题描述了新闻项目的用途和格式
标题
作者
简短（最多 50 个字符）的描述性标题。强制性。作者姓名和电子邮件地址，格式为真实姓名 <email@address>
。强制性；如果合适，可以指定多个作者标题。
翻译者
对于翻译的新闻项目，翻译者的姓名和电子邮件地址。如果合适，可以指定多个翻译者标题。
内容类型1.0仅在新闻项目格式中，它是强制性的，必须为.
text/plain
发布日期发布日期，格式为格式（例如 2005-12-18）以兼容 GLEP 45 [10]。日期必须以 UTC（协调世界时）表示。翻译应使用原始新闻项目的日期。必填。
修订版本
初始版本为 1。每当对新闻项目进行更改时，都应递增。需要重新阅读新闻项目的更改（即，大多数与拼写或格式无关的更改）应使用新的新闻项目。必填。
新闻项目格式
已知的格式有1.0和2.0。格式的未来修订版可能会为向前兼容的更改递增次要版本号（即，仍然允许旧工具处理新格式），或为重大更改递增主要版本号。

以下标题用于过滤

Display-If-Installed
包依赖项规范（例如，>=sys-devel/gcc-5或www-servers/apache) 符合新闻项目格式中的 EAPI 0 [18]1.0或格式中的 EAPI 52.0。如果用户已从获取新闻项目的仓库中安装了指定的包，则应显示新闻项目。
Display-If-Keyword
关键字 [7]名称，例如mips或x86-fbsd。如果用户处于相关的关键字下，则应显示新闻项目。
Display-If-Profile
配置文件路径，例如default/linux/sparc/13.0。如果用户使用的是相关的精确配置文件，则应显示新闻项目。此标题可用于替换已弃用文件。在新闻项目格式中2.0，斜线后紧跟的终端星号充当任何后续路径组件的通配符，例如default/linux/*.

新闻项目文件的内容将包含一个 RFC 822 样式的标题 [13]，然后是纯文本格式的消息主体。本 GLEP 定义了各种可选和强制标题。未来的 GLEP 可能会提出新的标题——处理这些新闻项目的工具必须忽略任何无法识别的标题。

在执行包移动时，开发人员还必须更新新闻文件中的任何相关Display-If-Installed标题。

用于确定新闻项目是否“相关”的算法如下

  • 对于每个Display-If-至少出现一次的标题类型
    • 如果此类型的标题均未成功匹配，则新闻项目不相关。
  • 否则，新闻项目相关。

特别是，如果未指定Display-If-标题，则新闻项目将对所有用户相关。

选择此算法是因为它使诸如“为YourSQL用户显示此新闻项目，这些用户位于sparc或x86-obsd上”之类的条件相对易于指定——据信，这些类型的条件比“为使用YourSQL的用户显示此新闻项目，或为位于sparc或x86-obsd上的人员显示此新闻项目”或“为使用YourSQL且同时位于sparc和x86-obsd".

新闻项目正文

上的人员显示这些新闻项目”更可能出现。

标题部分必须后跟一个空行，然后是文本的主体。

文本主体应在 72 个字符处换行。不应使用任何花哨的格式或制表符——新闻项目可能直接显示在终端上。段落应以空行分隔。

新闻项目示例

超链接可用于引用更多信息（例如，升级指南）。但是，新闻项目的主体应具有描述性，而不仅仅是“阅读此链接”的文本。假设用户可以在某个地方访问 Web 浏览器，但不一定在正在管理的机器上——例如，在许多服务器和路由器上都会出现这种情况。YourSQL数据库格式的升级可能会破坏向前兼容性，此假设的新闻项目可用于此类升级。

新闻项目质量控制

过去曾有人抱怨某些升级通知和新闻项目的可理解性。这是可以理解的——并非每个 Gentoo 开发人员都以英语为母语。但是，为了清楚起见，为了专业性，以及为了避免让我们看起来像傻瓜，在将新闻项目强加给最终用户之前，务必更正任何语言问题。

因此，在提交拟议的新闻项目之前至少 72 小时，必须将其发布到gentoo-dev邮件列表中，并抄送给[email protected]（在特殊情况下可以例外）。任何投诉——例如关于措辞、清晰度或准确性的投诉——在新闻项目上线之前**必须**得到解决。

新闻项目只能用于可能导致严重升级或兼容性问题的**重要**更改。普通的升级消息和非关键新闻项目应保留在einfo通知中。建议书应证明消息对其目标受众的重要性。

树向用户推送新闻项目的解决方案。

过滤系统意味着可以发送面向罕见包或架构用户的新闻项目。因此，理由应为“此消息对 YourSQL 用户很重要，因为……”，而不是“YourSQL 很重要，因为……”。

新闻项目分发

服务器端

新闻项目将通过标准 rsync 树提供。这样就不需要轮询远程源。

将为新闻项目创建一个新的仓库。此仓库的类型（CVS 或 Subversion）、位置和访问控制不在本 GLEP 的范围内。

新闻项目文件的内容将包含一个 RFC 822 样式的标题 [13]，然后是纯文本格式的消息主体。本 GLEP 定义了各种可选和强制标题。未来的 GLEP 可能会提出新的标题——处理这些新闻项目的工具必须忽略任何无法识别的标题。

本 GLEP 的先前草案改用主gentoo-x86树。根据基础设施的建议 [12]对这一点进行了更改。这两种解决方案具有相同的结果。

此仓库的内容将自动与主 rsync 树合并，并将项目放置在metadata/news/目录中。用于合并这些项目的方法以及合并频率不在本 GLEP 的范围内；类似的设置已用于将 GLSAs 合并到 rsync 树中。

客户端

每当找到相关的未读新闻项目时，包管理器都会创建一个名为/var/lib/gentoo/news/news-${repoid}.unread的文件（如果该文件尚不存在），并在新行上追加新闻项目标识符（例如2005-11-01-yoursql-updates）。

所有与新闻项目相关的文件都应由 root 拥有，并位于portage组中，并设置组写（以及目录的执行）权限位。新闻文件应可供所有人读取。

将通过emerge工具以类似于现有“配置文件需要更新”消息的方式显示有关新相关新闻项目的通知

* Important: there are 5 unread news items.
* Type emerge --help news to learn how to read news files.

应显示检查新新闻消息

  • 在emerge sync
  • 在emerge --pretend
  • 之后emerge <target>之前（可能还包括红色警告消息）

包管理器不需要知道如何启动用户选择的新闻客户端。这与处理配置文件更新的方式一致。

包管理器可以使用时间戳检查文件以避免不必要地处理新闻项目。

包管理器必须跟踪已添加到未读列表中的新闻项目，以避免重复标记已删除的新闻项目。这可以通过news-${repoid}.skip文件来处理，该文件包含已添加到news-${repoid}.unread文件中的新闻项目的 ID，但此方法不是本 GLEP 的必需方法。

真正不关心新闻项目的用户可以使用rsync_excludes过滤掉metadata/news/目录。

新闻项目客户端

标记新闻项目以供阅读后，可以使用第三方工具（或传统的核心 Unix 工具）来显示和查看新闻文件。

阅读新闻项目后，应将其名称从news-${repoid}.unread文件中删除。如果新闻客户端充当交互式阅读器而不是网关，则应将其名称添加到同一目录中的news-${repoid}.read文件中，并使用相同的格式。

一个eselect [4]模块将被创建为“建议”显示工具；其他显示工具（例如，新闻到电子邮件转发器，对于在cron上同步的用户来说，这将是理想的选择）将作为选项保留给需要它们的用户。

新闻项目移除

当新闻项目不再相关时，如果它们被将来的新闻项目取代，或者在很长一段时间后，可以将其删除（通过从主树中删除新闻文件）。这与用于更新条目的方法相同。

与现有系统的集成

可以轻松地将这些新闻项目转换为 Gentoo 网站上新闻项目或gentoo-announce邮件列表

帖子中使用的格式。

向后兼容性

有一个现有的自动化工具 [5]用于将 GLSAs 发布到论坛。类似的工具可用于这些新闻项目。这里不涉及向后兼容性问题。现有工具将简单地忽略目录。

参考实现

news/

鸣谢

目录。

在 Paludis [15]中可以找到所需包管理器支持的参考实现，以及作为 eselect 模块 [16]实现的参考新闻阅读器。

示例文件

通过 Portage 通知用户新闻更新的想法来自 Stuart Herbert [17]。
感谢 Lance Albertson、Stephen Bennett、Donnie Berkholz、Grant Goodyear、Brian Harring、Marius Mauch、Dan Meltzer、Jason Stubbs、Paul de Vrieze 和 Alec Warner 的投入。此处介绍的一些想法是他们的，另一些则完全违背了他们的建议。

参考文献

[1]example-news-item.txt
[2]一个新闻项目的示例。
[3]BCP 47：“用于识别语言的标签”，https://tools.ietf.org/rfc/bcp/bcp47.txt
[4]Bugzilla Bug 11359“ [新功能] pkg_postinst/pkg_preinst ewarn/einfo 日志记录”，https://bugs.gentoo.org/show_bug.cgi?id=11359
[5]Gentoo XML 指南，Daniel Robbins 等人，https://gentoolinux.cn/doc/en/xml-guide.xml
[6]用于配置和管理实用程序的 eselect 模块化框架，https://gentoolinux.cn/proj/en/eselect/index.xml
[7]论坛用户 GLSA，http://forums.gentoo.org/profile.php?mode=viewprofile&u=55648
[8]GLEP 31：“Portage 树项目字符集”，Ciaran McCreesh，https://gentoolinux.cn/glep/glep-0031.html
[9]GLEP 34：“每个类别的 metadata.xml 文件”，Ciaran McCreesh，https://gentoolinux.cn/glep/glep-0034.html
[10]GLEP 45：“GLEP 日期格式”，Henrik Brix Andersen，https://gentoolinux.cn/glep/glep-0045.html
[11]GLEP 74：“使用清单文件进行全树验证”，Michał Górny，Robin Hugh Johnson，Ulrich Müller，https://gentoolinux.cn/glep/glep-0074.html
[12]“Re: [gentoo-dev] GLEP ??：关键新闻报道”，Lance Albertson，消息 ID [email protected]，https://archives.gentoo.org/gentoo-dev/message/4204839d4091758c3bad1dbd18ed16f7
[13]RFC 822“ARPA 互联网文本消息格式标准”
[14]RFC 3629：“UTF-8，ISO 10646 的转换格式” http://www.ietf.org/rfc/rfc3629.txt
[15]Paludis 主页，http://paludis.berlios.de
[16]news.eselect，http://svn.berlios.de/svnroot/repos/paludis/trunk/eselect/news.eselect
[17]“支持自动新闻机制”，Stuart Herbert，http://stu.gnqs.org/diary/gentoo.php/2005/10/28/favouring_an_automatic_news_mechanism
[18]https://wiki.gentoo.org/wiki/Project:Package_Manager_Specification