Re: [gentoo-dev] [DRAFT] GLEP 84: Standard format for package.mask files
> On Thu, 05 Oct 2023, Michał Górny wrote: >> 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 [#PMS-4.4]_ and 5.2.8 [#PMS-5.2.8]_. This >> GLEP >> further limits the syntax to one item per line, without any leading or >> proceeding whitespaces, no comments inside the packages list, and no blank >> lines between items in the list. > That kinda sucks. For very long masks, it is useful to be able to split > the entry into subgroups. I suppose it's technically still doable via > splitting the entry but that sounds a bit backwards. I think it could say that blank lines between items are allowed, without any other change to the spec. The fact that each entry must start with a comments block will still guarantee that assigning of packages to an entry will be well-defined. Ulrich signature.asc Description: PGP signature
Re: [gentoo-dev] [DRAFT] GLEP 84: Standard format for package.mask files
> On Thu, 05 Oct 2023, Arthur Zamarin wrote:
> On 05/10/2023 06.12, Michał Górny wrote:
>> This is inconsistent with the current usage, and confusing. "After"
>> makes it unclear whether the list is inclusive (i.e. "remove on that day
>> or later") or exclusive ("remove the next day or later"),
>> and in the latter case it's quite backwards.
> Hmm, I don't really care what word we use here, but I do want us to
> agree on one word (cause I'll need to update `pkgdev mask`). Some of the
> considerations against "on" (currently used) is the fact: does it mean
> it isn't fine to remove after it?
> Does English has a nice word for ">= time"?
Make it "on", because the date specified is the intended removal date
when the entry is added.
That is, users cannot rely on the package still being present at any
later date.
Ulrich
signature.asc
Description: PGP signature
Re: [gentoo-dev] [DRAFT] GLEP 84: Standard format for package.mask files
On 05/10/2023 06.12, Michał Górny wrote: > On Wed, 2023-10-04 at 21:43 +0300, Arthur Zamarin wrote: >> Specification >> = >> >> ... >> >> Must conform to PMS sections 4.4 [#PMS-4.4]_ and 5.2.8 [#PMS-5.2.8]_. This >> GLEP >> further limits the syntax to one item per line, without any leading or >> proceeding whitespaces, no comments inside the packages list, and no blank >> lines between items in the list. > > That kinda sucks. For very long masks, it is useful to be able to split > the entry into subgroups. I suppose it's technically still doable via > splitting the entry but that sounds a bit backwards. > Good point. I'll update the draft to allow single blank lines between package lists, but I'll still add recommendation to consider splitting into multiple separate masks. -- Arthur Zamarin arthur...@gentoo.org Gentoo Linux developer (Python, pkgcore stack, Arch Teams, GURU) OpenPGP_signature.asc Description: OpenPGP digital signature
Re: [gentoo-dev] [DRAFT] GLEP 84: Standard format for package.mask files
On 05/10/2023 06.12, Michał Górny wrote:
> "Block" in two meanings, confusing.
Thanks for the improvements, I'll apply them soon on the branch, and
send as DRAFT v2 when some more changes collect.
>
>> explanation where needed. If referencing bugs, use the `bugs list`_ format
>> (mask rendering tools should render mentioned bugs also in this part).
>>
>> In this part, a paragraph separator is a blank line, similar to
>> ReStructuredText
>> format. Using multiple blank lines between paragraphs is prohibited.
>>
>> Last-Rite Epilogue
>> ''
>>
>> If the last paragraph starts with "Removal after", then this mask entry is
>> considered as last-rite mask, and the last paragraph must conform to the
>> last-rite epilogue format.
>
> This is inconsistent with the current usage, and confusing. "After"
> makes it unclear whether the list is inclusive (i.e. "remove on that day
> or later") or exclusive ("remove the next day or later"),
> and in the latter case it's quite backwards.
>
Hmm, I don't really care what word we use here, but I do want us to
agree on one word (cause I'll need to update `pkgdev mask`). Some of the
considerations against "on" (currently used) is the fact: does it mean
it isn't fine to remove after it?
Does English has a nice word for ">= time"?
--
Arthur Zamarin
arthur...@gentoo.org
Gentoo Linux developer (Python, pkgcore stack, Arch Teams, GURU)
OpenPGP_signature.asc
Description: OpenPGP digital signature
Re: [gentoo-dev] [DRAFT] GLEP 84: Standard format for package.mask files
On Wed, 2023-10-04 at 21:43 +0300, Arthur Zamarin wrote:
> Specification
> =
>
> 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 [#CURR-MASK]_,
> as mentioning the GLEP is enough.
>
> Files can decide to add some extra file documentation, in which case, the
> entries start after the line:
>
> #--- END OF EXAMPLES ---
>
> 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 [#PMS-4.4]_ and 5.2.8 [#PMS-5.2.8]_. This
> GLEP
> further limits the syntax to one item per line, without any leading or
> proceeding whitespaces, no comments inside the packages list, and no blank
> lines between items in the list.
That kinda sucks. For very long masks, it is useful to be able to split
the entry into subgroups. I suppose it's technically still doable via
splitting the entry but that sounds a bit backwards.
> Comments Block
> --
>
> 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 whitespaces should be dropped.
"Trailing whitespace".
>
> The comments block is prefixed with a "#" symbol. The comments should be
"The lines in the comment block are ..."
> 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 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.
"To simplify the specification, the following sections will skip
mentioning the "#" prefix." (still imperfect)
> Explanation
> '''
>
> In this block the reasons for the block should be listed, with extra
"Block" in two meanings, confusing.
> explanation where needed. If referencing bugs, use the `bugs list`_ format
> (mask rendering tools should render mentioned bugs also in this part).
>
> In this part, a paragraph separator is a blank line, similar to
> ReStructuredText
> format. Using multiple blank lines between paragraphs is prohibited.
>
> Last-Rite Epilogue
> ''
>
> If the last paragraph starts with "Removal after", then this mask entry is
> considered as last-rite mask, and the last paragraph must conform to the
> last-rite epilogue format.
This is inconsistent with the current usage, and confusing. "After"
makes it unclear whether the list is inclusive (i.e. "remove on that day
or later") or exclusive ("remove the next day or later"),
and in the latter case it's quite backwards.
--
Best regards,
Michał Górny
[gentoo-dev] [DRAFT] GLEP 84: Standard format for package.mask files
Hi all
As result of the discussion on gentoo-dev ML [1], I've been working on a
GLEP for the standard format for package.mask files. I've tried to
incorporate all the things spoken on that thread.
Currently this GLEP draft can be found on the glep-0084 branch [2].
Please also note that English isn't my first language (and also not
second), so if you think any paragraph isn't quite readable or simple to
understand, feel free to suggest improvements - nothing will be taken as
offense.
As noted in the draft, some of the TODOs is implementing this GLEP in
pkgcheck, pkgdev, and soko. I know that implementing the GLEP isn't a
requirement to accept the GLEP, but this should be simple enough and
should show the GLEP is mature enough.
[1]
https://public-inbox.gentoo.org/gentoo-dev/b2a2515f-8c1e-4422-8cec-cd4fe3a47...@gentoo.org/T/#u
[2] https://gitweb.gentoo.org/data/glep.git/tree/glep-0084.rst?h=glep-0084
---
GLEP: 84
Title: Standard format for package.mask files
Author: Arthur Zamarin
Type: Standards Track
Status: Draft
Version: 1.0
Created: 2023-09-30
Content-Type: text/x-rst
---
Abstract
This GLEP specifies the format of ``package.mask`` files under profiles
directory.
Motivation
==
At the moment of writing this GLEP, ``package.mask`` files didn't have a full
format specification. While PMS sections 4.4 [#PMS-4.4]_ and 5.2.8
[#PMS-5.2.8]_ specifies the raw format which the package manager must support
for correct behavior, it does not specify how comments must be formatted, how
entries must be grouped, how last-rite masks should be written, etc.
Various tools have been developed to handle that mask message. A non exhaustive
list includes ``lr-add-pmask`` [#lr-add-pmask]_, ``pkgdev mask``
[#pkgdev-mask]_,
and ``soko`` [#soko-mask]_. Those tools have different purposes, filing a new
mask message with all relevant information, and showing a nice rendered mask
message to users. Those tools are very complicated (since they need to handle
various edge cases of existing masks, and try to prepare for future mask
messages).
For a long time, ``profiles/package.mask`` had a special header [#CURR-MASK]_
whose purpose was to define the mask message formatting. While it has served
its purpose for a long time indeed, it still left a lot of wiggle room for the
message.
Therefore, the motivation for this GLEP is to provide unified, clear and
complete specification for package.mask entries across the repository.
Specification
=
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 [#CURR-MASK]_,
as mentioning the GLEP is enough.
Files can decide to add some extra file documentation, in which case, the
entries start after the line:
#--- END OF EXAMPLES ---
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 [#PMS-4.4]_ and 5.2.8 [#PMS-5.2.8]_. This GLEP
further limits the syntax to one item per line, without any leading or
proceeding whitespaces, no comments inside the packages list, and no blank
lines between items in the list.
Comments Block
--
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 whitespaces should be dropped.
The comments block is 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 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.
Author Line
'''
A line of the format: ``${AUTHOR-NAME} <${EMAIL}> (${SINGLE-DATE})``. The author
name and email should correspond to the mask author, and should confirm to the
GLEP 76 rules. The date should be of RFC-3339 full-date format, meaning
``-MM-DD``. The date is recommended to use the date at UTC timezone at the
moment of commit push.
Explanation
'''
In this block the reasons for the block should be listed, with extra
explanation where needed. If referencing bugs, use the `bugs list`_ format
(mask re
