获取 Gentoo！

GLEP 84：package.mask 文件的标准格式

作者 Arthur Zamarin <arthurzam@gentoo.org>
类型 标准跟踪
状态 最终版
版本 1.0
创建日期 2023-11-01
上次修改日期 2024-09-26
发布历史 2023-10-04, 2023-10-13, 2023-11-01
GLEP 源代码 glep-0084.rst

摘要

本 GLEP 指定了以下文件的格式：package.mask位于 profiles 目录下的文件。

动机

在撰写本 GLEP 时，package.mask这些文件没有完整的格式规范。虽然 PMS 第 4.4 节 [1] 和 5.2.8 节 [2] 指定了包管理器为确保正确行为必须支持的原始格式，但它没有指定注释的格式、条目的分组方式、最后期限屏蔽的编写方式等。

已经开发了各种工具来处理屏蔽消息。一个不完整的列表包括lr-add-pmask [4], pkgdev mask [5] 和soko [6]。这些工具有不同的用途，使用所有相关信息填写新的屏蔽消息，并向用户显示渲染后的屏蔽消息。这些工具非常复杂（因为它们需要处理现有屏蔽的各种极端情况，并尝试为将来的屏蔽消息做好准备）。

长期以来，profiles/package.mask有一个特殊的头部 [3]，其目的是定义屏蔽消息的格式。虽然它确实在很长一段时间内发挥了作用，但它仍然为消息留下了很大的回旋余地。

因此，本 GLEP 的动机是为整个代码库中的 package.mask 条目提供统一、清晰和完整的规范。

规范

条目分组

每个屏蔽条目包含 2 个部分：注释块 和 软件包列表，这两部分之间没有空行。条目之间必须出现一个强制性的空行。

添加到文件中的新条目必须插入到开头，在文件头部之后。

软件包列表

必须符合 PMS 第 4.4 节 [1] 和 5.2.8 节 [2] 的规定。本 GLEP 进一步限制了语法，每行一个项目，没有前导或尾随空格，软件包列表中没有注释。项目之间允许使用空行。

注释块

注释块中的行以“#”符号为前缀。注释应与“#”之间用单个空格隔开，除非这是尾随空格，在这种情况下应将其删除（这意味着注释块中的空行仅为“#\n”）。

注释块包含 2 个必填部分（作者行 和 说明）和一个可选部分（最后期限结语）。用于分隔部分的空行是可选的。应删除尾随空格。

注释块的行应使用 80 个字符的列换行（包括“#”前缀）。作者行不包含在此最大宽度内。

为了简化说明，我们不会提及“#”前缀。建议实现删除此前缀，然后再进一步处理块。

作者行

格式为以下行：${AUTHOR-NAME} <${EMAIL}> (${SINGLE-DATE})。作者姓名和电子邮件应与屏蔽作者相对应，并应符合 GLEP 76 规则。日期应为 RFC-3339 全日期格式，即YYYY-MM-DD。建议日期使用提交推送时 UTC 时区的日期。

说明

在此块中，应列出屏蔽的原因，并在需要时提供额外的说明。如果引用 Bug，请使用 Bug 列表 格式（屏蔽渲染工具也应在此部分中渲染提到的 Bug）。

在此部分中，段落分隔符是一个空行，类似于 ReStructuredText 格式。禁止在段落之间使用多个空行。

最后期限结语

如果最后一段以“Removal on”开头，则此屏蔽条目将被视为最后期限屏蔽，并且最后一段必须符合最后期限结语格式。

该段落应采用以下格式：Removal on {DATE}[.,]? +{BUGS-LIST}.?，其中日期为 RFC-3339 全日期格式，即YYYY-MM-DD，并且 Bug 列表采用 Bug 列表 格式。列出的 Bug 应包括打开的最后期限 Bug，以及可能未在说明段落中列出的其他相关 Bug。

Bug 列表

Bug 列表应以匹配正则表达式"[Bb]ugs?"（Bug、Bugs、bug、bugs）的单词开头，后跟一个空格，以及一个逗号分隔的 Bug 编号列表，其中每个 Bug 编号以“#”符号开头。例如Bugs #667687, #667689。Bug 列表的解析器应处理由于长度而导致的 Bug 列表换行。

基本原理

不使用硬编码格式

虽然使用硬编码格式（例如 TOML、XML、INI）可能是未来正确的路径，但在撰写本 GLEP 时，更倾向于使用与大多数屏蔽类似的格式。此外，本 GLEP 更倾向于使用接近于组织良好的自由文本的格式。

Bug 列表的特定格式

最好指定 Bug 列表的确切预期格式，以便渲染工具（例如soko）可以将 Bug 编号渲染为链接。存在其他用于提取 Bug 编号的用例，例如用于清理最后期限软件包的新工具。

日期使用 UTC 时区

为像 Gentoo 这样的国际项目指定时区非常明智。虽然由于时区导致仅日期时间戳的差异不太可能发生，但标准化 UTC 的主要目的是防止新条目日期早于现有条目的情况。由于建议使用工具（例如 pkgdev mask）创建屏蔽条目，因此该工具应生成正确的日期，这对于用户来说应该是透明的。

不允许“X 天后移除”

最后期限结语的另一种现有变体是使用“X 天后移除”。这使得了解最后期限日期变得复杂，因为用户需要计算正确的日期（考虑同一月的天数）。存在帮助填写屏蔽条目的工具意味着计算移除日期对于编写者来说很简单。允许“X 天后移除”格式没有任何好处。

向后兼容性

本规范不会破坏 PMS 中指定的原始条目格式，这意味着所有符合 PMS 要求的现有包管理器实现也将支持此新规范。

但是，需要手动更新多个现有条目以符合新规范，以便更新后的工具可以解析和处理所有现有条目。只有在修复所有条目后，才能添加特殊的头部，选择使用新格式。建议可能用于覆盖层的工具在遇到不符合规范的条目时不要崩溃，并验证此特殊头部是否存在。

参考实现

BNF 语法

BUGS-LIST    ::= [Bb]ugs? #\d+(,? #\d+)*
             ::= [Bb]ugs? +#\d+(,? +#\d+)*
DATE         ::= YYYY-MM-DD
LAST-RITE    ::= Removal on {DATE}[.,]? +{BUGS-LIST}.?
AUTHOR-LINE  ::= {AUTHOR-NAME} <{AUTHOR-EMAIL}> ({DATE})
PARAGRAPH    ::= # [^\n]+(\n# [^\n]+)*
EXPLANATION  ::= {PARAGRAPH}(\n#\n{PARAGRAPH})*
MASK-COMMENT ::= # {AUTHOR-LINE}\n{EXPLANATION}
             ::= # {AUTHOR-LINE}\n{EXPLANATION}\n# {LAST-RITE}
PKGS_GROUP   ::= {DEP}(\n{DEP})*
MASK-PKGS    ::= {PKGS_GROUP}(\n+{PKGS_GROUP})*
ENTRY        ::= {MASK-COMMENT}\n{MASK-PKGS}
ENTRIES      ::= {ENTRY}(\n\n{ENTRY})*
GLEP-HEADER  ::= # Uses GLEP 84 format
SEPARATION   ::= # -{5,}.*-{5,}
FILE         ::= {COPYRIGHT}\n+{GLEP-HEADER}\n{ENTRIES}
             ::= {COPYRIGHT}\n+{GLEP-HEADER}\n+{COMMENTS}\n+{SEPARATION}\n{ENTRIES}
             ::= {COPYRIGHT}\n+{GLEP-HEADER}\n+{COMMENTS}\n+{SEPARATION}\n{ENTRIES}\n{SEPARATION}\n+{COMMENTS}

示例条目

# Arthur Zamarin <arthurzam@gentoo.org> (2023-09-21)
# Very broken, no idea why packaged, need to drop ASAP. The project
# is done with supporting this package. See for history bug #667889.
#
# As a better plan, you should migrate to dev-lang/perl, which has
# better compatibility with dev-lang/ruby when used with dev-lang/lua
# bindings.
# Removal on 2023-10-21.  Bugs #667687, #667689.
dev-lang/python

# Arthur Zamarin <arthurzam@gentoo.org> (2023-09-20)
# Normal mask for testing
dev-lang/lua:5.1