From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from lists.gentoo.org (pigeon.gentoo.org [208.92.234.80]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits)) (No client certificate requested) by finch.gentoo.org (Postfix) with ESMTPS id 36DD7158089 for ; Wed, 4 Oct 2023 18:43:42 +0000 (UTC) Received: from pigeon.gentoo.org (localhost [127.0.0.1]) by pigeon.gentoo.org (Postfix) with SMTP id 748F42BC109; Wed, 4 Oct 2023 18:43:38 +0000 (UTC) Received: from smtp.gentoo.org (smtp.gentoo.org [IPv6:2001:470:ea4a:1:5054:ff:fec7:86e4]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (No client certificate requested) by pigeon.gentoo.org (Postfix) with ESMTPS id 355E92BC02F for ; Wed, 4 Oct 2023 18:43:38 +0000 (UTC) Message-ID: Date: Wed, 4 Oct 2023 21:43:26 +0300 Precedence: bulk List-Post: List-Help: List-Unsubscribe: List-Subscribe: List-Id: Gentoo Linux mail X-BeenThere: gentoo-dev@lists.gentoo.org Reply-to: gentoo-dev@lists.gentoo.org X-Auto-Response-Suppress: DR, RN, NRN, OOF, AutoReply MIME-Version: 1.0 User-Agent: Mozilla Thunderbird Content-Language: en-US To: gentoo-dev@lists.gentoo.org, glep@gentoo.org From: Arthur Zamarin Subject: [gentoo-dev] [DRAFT] GLEP 84: Standard format for package.mask files Content-Type: multipart/signed; micalg=pgp-sha256; protocol="application/pgp-signature"; boundary="------------0zgHETgrqF034yqNAzo909c0" X-Archives-Salt: ee1da950-abb7-4010-ae00-e1fa62be306d X-Archives-Hash: 557bc9a3d85360956650e23b74fa6568 This is an OpenPGP/MIME signed message (RFC 4880 and 3156) --------------0zgHETgrqF034yqNAzo909c0 Content-Type: multipart/mixed; boundary="------------1cMuM5n1SEOIiCPa0EsyoiZF"; protected-headers="v1" From: Arthur Zamarin Reply-To: gentoo-dev@lists.gentoo.org To: gentoo-dev@lists.gentoo.org, glep@gentoo.org Message-ID: Subject: [DRAFT] GLEP 84: Standard format for package.mask files --------------1cMuM5n1SEOIiCPa0EsyoiZF Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: quoted-printable 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-cd= 4fe3a4727c@gentoo.org/T/#u [2] https://gitweb.gentoo.org/data/glep.git/tree/glep-0084.rst?h=3Dglep-0= 084 --- 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 =3D=3D=3D=3D=3D=3D=3D=3D This GLEP specifies the format of ``package.mask`` files under profiles directory. Motivation =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D 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 sup= port 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 exha= ustive 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 m= ask message to users. Those tools are very complicated (since they need to ha= ndle 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-MA= SK]_ whose purpose was to define the mask message formatting. While it has ser= ved its purpose for a long time indeed, it still left a lot of wiggle room fo= r the message. Therefore, the motivation for this GLEP is to provide unified, clear and complete specification for package.mask entries across the repository. Specification =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D Header ------ As an opt-in GLEP for files, files which want to use this GLEP format sho= uld 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 copyr= ight header. The line should be: # Uses GLEP 84 format This header should come instead of the current very long header [#CURR-MA= SK]_, 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 entri= es, a mandatory blank line must appear. New entries added to the file must be inserted at the beginning, after th= e file header. Packages List ------------- Must conform to PMS sections 4.4 [#PMS-4.4]_ and 5.2.8 [#PMS-5.2.8]_. Thi= s GLEP further limits the syntax to one item per line, without any leading or proceeding whitespaces, no comments inside the packages list, and no blan= k 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 li= ne 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 whitesp= ace, 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 characte= rs (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 t= o the GLEP 76 rules. The date should be of RFC-3339 full-date format, meaning ``YYYY-MM-DD``. The date is recommended to use the date at UTC timezone a= t 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`_ forma= t (mask rendering tools should render mentioned bugs also in this part). In this part, a paragraph separator is a blank line, similar to ReStructu= redText format. Using multiple blank lines between paragraphs is prohibited. Last-Rite Epilogue '''''''''''''''''' If the last paragraph starts with "Removal after", then this mask entry i= s considered as last-rite mask, and the last paragraph must conform to the last-rite epilogue format. The paragraph should be of format ``Removal after ${DATE}. ${BUGS-LIST}``= , where the date is RFC-3339 full-date format, meaning ``YYYY-MM-DD``, and = the bugs list is of the `bugs list`_ format. The listed bugs should include t= he last-rite bug opened, and potentially more relevant bugs which weren't li= sted in the explanation paragraphs. Bugs List ''''''''' A list of bugs should start with a word matching the regular expression ``"[Bb]ugs?"`` (Bug, Bugs, bug, bugs), a single space, and a comma-separa= ted list of bug numbers, where each bug number starts with "#" symbol. For ex= ample ``Bugs #667687, #667689``. Parsers for bugs list should handle bugs list wrapping to multiple lines because of its length. Rationale =3D=3D=3D=3D=3D=3D=3D=3D=3D 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 fo= r tree-cleaning last-rited packages. UTC time zone for dates ----------------------- Specifying a time zone is quite sensible for an international project suc= h 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 th= e 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 generat= e 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 day= s". It complicates the knowledge of the last date, since the user needs to compu= te 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 "rem= oval in X days" format. Backwards Compatibility =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D This specification does not break the raw entries format specified in PMS= , meaning all existing package managers implementations confirming to PMS w= ill also support this new specification. However, multiple existing entries would need to be manually updated to c= onform to the new specification, so the updated tools can parse and work with al= l existing entries. Only after fixing all entries, the special header shoul= d be added, opting in the new format. Tools which might be used for overlays a= re recommended to not crash upon non-confirming entries, and verify the exis= tence of this special header. Reference Implementation =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =2E. TODO: add reference implementations for: 1. pkgcheck check for confirming format 2. pkgdev updated for new format 3. soko updated to use new format BNF Grammar ----------- =2E. code:: bnf BUGS-LIST ::=3D [Bb]ugs? #\d+(, +#\d+)* DATE ::=3D YYYY-MM-DD LAST-RITE ::=3D Removal after {DATE}. +{BUGS-LIST}.? AUTHOR-LINE ::=3D {AUTHOR-NAME} <{AUTHOR-EMAIL}> ({DATE}) PARAGRAPH ::=3D # [^\n]+(\n# [^\n]+)* EXPLANATION ::=3D {PARAGRAPH}(\n#\n{PARAGRAPH})* MASK-COMMENT ::=3D # {AUTHOR-LINE}\n{EXPLANATION} ::=3D # {AUTHOR-LINE}\n{EXPLANATION}\n# {LAST-RITE} MASK-PKGS ::=3D {ATOM}(\n{ATOM})* ENTRY ::=3D {MASK-COMMENT}\n{MASK-PKGS} Example Entries --------------- =2E. code:: # Arthur Zamarin (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 after 2023-10-21. Bugs #667687, #667689. dev-lang/python # Arthur Zamarin (2023-09-20) # Normal mask for testing dev-lang/lua:5.1 References and Footnotes =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =2E. [#PMS-4.4] "PMS section 4.4" (https://projects.gentoo.org/pms/8/pms.html#x1-320004.4) =2E. [#PMS-5.2.8] "PMS section 5.2.8" (https://projects.gentoo.org/pms/8/pms.html#x1-510005.2.8) =2E. [#CURR-MASK] "Existing ``packages.mask`` header before this GLEP" (https://gitweb.gentoo.org/repo/gentoo.git/tree/profiles/package.mask?= id=3D9acaae3e1a70ec6bd72e3c324b115bae1a05ed5f) =2E. [#lr-add-pmask] https://github.com/projg2/mgorny-dev-scripts/blob/52= ceab3a579b35fb0d92f7a1f060cd7d4659f24f/lr-add-pmask =2E. [#pkgdev-mask] https://gitweb.gentoo.org/proj/pkgcore/pkgdev.git/tre= e/src/pkgdev/scripts/pkgdev_mask.py?h=3Dv0.2.8 =2E. [#soko-mask] https://gitweb.gentoo.org/sites/soko.git/tree/pkg/porta= ge/repository/mask.go?h=3Dv1.0.3 Copyright =3D=3D=3D=3D=3D=3D=3D=3D=3D This work is licensed under the Creative Commons Attribution-ShareAlike 4= =2E0 International License. To view a copy of this license, visit https://creativecommons.org/licenses/by-sa/4.0/. --------------1cMuM5n1SEOIiCPa0EsyoiZF-- --------------0zgHETgrqF034yqNAzo909c0 Content-Type: application/pgp-signature; name="OpenPGP_signature.asc" Content-Description: OpenPGP digital signature Content-Disposition: attachment; filename="OpenPGP_signature.asc" -----BEGIN PGP SIGNATURE----- iQEzBAEBCgAdFiEE/axFlFuH2ptjtO5EAqCvUD0SBQQFAmUdsk4ACgkQAqCvUD0S BQR3mgf/aEI2eHbThVrI2+q6U+fepRBon1l6cdX963hnQpOlAzA0S964AW7fjjBZ nwmIZpsPN6SdFdET63tkHEc1BcYjj0fbou8PiLhjGGE16f+hoWA1bW7gduzSIVqN RXC8HDnbT3A09hjoimZcIAOoKklPsqd6p2SQ/PUMhbBvpbnnqcBEVxpg21pb2xTz rYn2Qd8zOy5ubu5wp8cLbHb+CuK2hSuvTf1kab4sNEJpO+f4bcf7A0aF5INHf0OK +/ryZOCPGZ2o+KPGsaHEF+wcqDO1zSl1oLtMH1N5FJDeaMZRMCwb6TFPXHeQjiqj eQr1NJFGDgG1/XhT7azfqVifjOizGg== =rpnu -----END PGP SIGNATURE----- --------------0zgHETgrqF034yqNAzo909c0--