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 9E7D2158089 for ; Wed, 1 Nov 2023 20:34:58 +0000 (UTC) Received: from pigeon.gentoo.org (localhost [127.0.0.1]) by pigeon.gentoo.org (Postfix) with SMTP id B97B52BC0D5; Wed, 1 Nov 2023 20:34:54 +0000 (UTC) Received: from smtp.gentoo.org (woodpecker.gentoo.org [140.211.166.183]) (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 693352BC0B1 for ; Wed, 1 Nov 2023 20:34:54 +0000 (UTC) Message-ID: <39fdb642-1947-4964-b559-ea31bb180303@gentoo.org> Date: Wed, 1 Nov 2023 22:34:42 +0200 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 Cc: glep@gentoo.org From: Arthur Zamarin Subject: [gentoo-dev] [DRAFT v3] GLEP 84: Standard format for package.mask files Content-Type: multipart/signed; micalg=pgp-sha256; protocol="application/pgp-signature"; boundary="------------7nEPAlsTdjQoTanpE0b6wStd" X-Archives-Salt: af9a3f78-de67-4b5f-8f80-01b1ddb15ad4 X-Archives-Hash: 8988f25758df825e8ce5eae977ed5890 This is an OpenPGP/MIME signed message (RFC 4880 and 3156) --------------7nEPAlsTdjQoTanpE0b6wStd Content-Type: multipart/mixed; boundary="------------vMfAdAF0jp0txP109DTnnPH0"; protected-headers="v1" From: Arthur Zamarin Reply-To: gentoo-dev@lists.gentoo.org To: gentoo-dev@lists.gentoo.org Cc: glep@gentoo.org Message-ID: <39fdb642-1947-4964-b559-ea31bb180303@gentoo.org> Subject: [DRAFT v3] GLEP 84: Standard format for package.mask files --------------vMfAdAF0jp0txP109DTnnPH0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: quoted-printable This is the third version of the GLEP after previous recommendations and suggestions [1] - thank you for all who participated. Similar to previously, the draft can also be found on glep-0084 branch [2]. [1] https://public-inbox.gentoo.org/gentoo-dev/uzg0mqpfc@gentoo.org/T/ [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-11-01 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 first separation line comment which begins and en= ds 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 separati= on line may appear, after which all comments are also ignored. Those separat= ion 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 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 tr= ailing whitespace, no comments inside the packages list. Blank lines between ite= ms are allowed. Comments Block -------------- The lines in the comment block are prefixed with a "#" symbol. The commen= ts should be separated with single space from the "#", unless this is traili= ng whitespace, in which case it should be removed (meaning blank lines in co= mments 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 li= ne to separate the parts is optional. Trailing whitespace should be dropped. 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 mask should be listed, with extra expla= nation where needed. If referencing bugs, use the `bugs list`_ format (mask rend= ering 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 on", then this mask entry is considered as last-rite mask, and the last paragraph must conform to the last-rite epilogue format. The paragraph should be of format ``Removal on {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+)* ::=3D [Bb]ugs? +#\d+(,? +#\d+)* DATE ::=3D YYYY-MM-DD LAST-RITE ::=3D Removal on {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} PKGS_GROUP ::=3D {DEP}(\n{DEP})* MASK-PKGS ::=3D {PKGS_GROUP}(\n+{PKGS_GROUP})* ENTRY ::=3D {MASK-COMMENT}\n{MASK-PKGS} ENTRIES ::=3D {ENTRY}(\n\n{ENTRY})* GLEP-HEADER ::=3D # Uses GLEP 84 format SEPARATION ::=3D # -{5,}.*-{5,} FILE ::=3D {COPYRIGHT}\n+{GLEP-HEADER}\n{ENTRIES} ::=3D {COPYRIGHT}\n+{GLEP-HEADER}\n+{COMMENTS}\n+{SEPARA= TION}\n{ENTRIES} ::=3D {COPYRIGHT}\n+{GLEP-HEADER}\n+{COMMENTS}\n+{SEPARA= TION}\n{ENTRIES}\n{SEPARATION}\n+{COMMENTS} 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 on 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/. --------------vMfAdAF0jp0txP109DTnnPH0-- --------------7nEPAlsTdjQoTanpE0b6wStd 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/axFlFuH2ptjtO5EAqCvUD0SBQQFAmVCtmIACgkQAqCvUD0S BQSFdAgAwV4cbqDH3qra+vVcD5jTpzqYb6ofR8QgZPwaaaF91zztz3isMuXc4QXO rwH3Wj5K0w3xB/8jq2bnbAqtLi8MXuqLFDDKM74WhU2WHeP1qr94HnRljGPCZXLV be/en8Ts5mAlLCFMSH+0GejmEJ4YZu7mfMU/2fo+xdLkEYk7/lnJrRRQkZa7j/IG tdV3QIvZDYl9ui2uQNP3uPFouxcxjzbLo+wtT7Hxzxc14poIRc64sxA72EdlIW1k VZInzHzlSArBURrFd/jD2HBpaPfhEqRuB5YxnEqUqZF0Rvb34uT1ob+48lE4S10f gsigUKUpoJgYLvaQ6LZrMHcTnerlTA== =VMy9 -----END PGP SIGNATURE----- --------------7nEPAlsTdjQoTanpE0b6wStd--