GLEP 84: Standard format for package.mask files

Header

As an opt-in GLEP for files, files which want to use this GLEP format should define a special header line which tools should use to know the format of the file. This line should appear as the first non empty line after the copyright header. The line should be:

# Uses GLEP 84 format

This header should come instead of the current very long header [3], as mentioning the GLEP is enough.

Files can decide to add some extra file documentation, in which case, the entries start after the first separation line comment which begins and ends with at least 5 "-", matching to the regex:

# -{5,}.*-{5,}

All comments before the first occurrence of this separation line comment are ignored, and should be considered as file documentation. Another separation line may appear, after which all comments are also ignored. Those separation lines are optional, and are not required for the file to conform to this GLEP.

Entries Grouping

Each mask entry consists of 2 parts: comments block and packages list, which aren't separated by a blank line between the 2 parts. Between entries, a mandatory blank line must appear.

New entries added to the file must be inserted at the beginning, after the file header.

Packages List

Must conform to PMS sections 4.4 [1] and 5.2.8 [2]. This GLEP further limits the syntax to one item per line, without any leading or trailing whitespace, no comments inside the packages list. Blank lines between items are allowed.

Comments Block

The lines in the comment block are prefixed with a "#" symbol. The comments should be separated with single space from the "#", unless this is trailing whitespace, in which case it should be removed (meaning blank lines in comments block are just "#n").

The comments block consists of 2 mandatory parts (author line and explanation) and one optional part (last-rite epilogue). A blank line to separate the parts is optional. Trailing whitespace should be dropped.

The lines of the comments block should use column wrapping of 80 characters (including the "#" prefix). The author line is excluded from this maximum width.

For simplifying the explanation, we wouldn't mention the "#" prefix. Implementations are advised to drop this prefix before further processing the block.

Not using a hard-coded format

While using a hard coded format, of some key-value kind (for example TOML, XML, INI), might be the correct path in the future, for the moment of writing this GLEP, it is preferred to stay with a format resembling most of the masks. Also, this GLEP prefers staying with a format close to an organized free-text.

Specific format for bugs list

It is preferable to specify the exact expected format for the bugs list, so rendering tools (such as soko) can render the bugs numbers as links. Other use-cases for extracting the bug numbers exist, for example a new tool for tree-cleaning last-rited packages.

UTC time zone for dates

Specifying a time zone is quite sensible for an international project such as Gentoo. While a difference in a date-only timestamp because of time zone is quite unlikely, the main purpose of standardizing on UTC is to prevent the case of new entries having a date prior to existing one. Since creating a mask entry using tools (such as pkgdev mask) is recommended, the tool should generate the correct date, which should be transparent to the user.

Disallow "removal in X days"

Another existing variant of last-rite epilogue is using "removal in X days". It complicates the knowledge of the last date, since the user needs to compute what is the correct date (consider the amount of days in the same month). The existence of tools helping to file mask entries means that computing the removal date is simple for the writer. No gain is seen from allowing "removal in X days" format.

BNF Grammar

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}

Example Entries

# 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