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 26709158089 for ; Thu, 21 Sep 2023 19:40:24 +0000 (UTC) Received: from pigeon.gentoo.org (localhost [127.0.0.1]) by pigeon.gentoo.org (Postfix) with SMTP id B4C752BC084; Thu, 21 Sep 2023 19:40:19 +0000 (UTC) Received: from smtp.gentoo.org (dev.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 7F0712BC017 for ; Thu, 21 Sep 2023 19:40:19 +0000 (UTC) Message-ID: Date: Thu, 21 Sep 2023 22:40:05 +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 From: Arthur Zamarin Subject: [gentoo-dev] Standard parsable format for profiles/package.mask file Content-Type: multipart/signed; micalg=pgp-sha256; protocol="application/pgp-signature"; boundary="------------mYjePsKsXg7eSb7niywg0r0F" X-Archives-Salt: 5651322c-0877-43cf-a11b-1f80aba9f029 X-Archives-Hash: cc5a227d2c26a22ef7b34c0bee234a35 This is an OpenPGP/MIME signed message (RFC 4880 and 3156) --------------mYjePsKsXg7eSb7niywg0r0F Content-Type: multipart/mixed; boundary="------------pUSBHvcD0ZYRkE4PAgc0AVbR"; protected-headers="v1" From: Arthur Zamarin Reply-To: gentoo-dev@lists.gentoo.org To: gentoo-dev@lists.gentoo.org Message-ID: Subject: Standard parsable format for profiles/package.mask file --------------pUSBHvcD0ZYRkE4PAgc0AVbR Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: quoted-printable Hi all I want to suggest a standard format for profiles/package.mask, for multiple reasons: 1. Easier to write simple to understand mask or last-rites entries. When all entries are in similar format, the reader knows where to expect important information and such. Also easier for writer to convey all needed information. 2. We can teach tools to parse it and render nicely, or help you fill the file. For example I've tried to implement a parser for packages.gentoo.org so it shows as nice as possible the message, see as example [1]. On the other hand, `pkgdev mask` [2] can help you fill the message (including bug number, last-rite until date, author & email line). Both of them mostly works, but when someone "breaks" the unofficial syntax, the tools fail sadly. This is why I want to recommend we create a mostly standard syntax, so we can all expect the same thing and have nice things. Also please note that for now I want to formalize the format only for profiles/package.mask file, and not the one inside all the different profiles. If you think we better apply to all of them, we can think on it separately please :) The current format is mostly acceptable, but let's tighten it. I will implement a pkgcheck check that will validate the format and error out if invalid. [1] https://packages.gentoo.org/packages/sys-fs/eudev [2] https://pkgcore.github.io/pkgdev/man/pkgdev/mask.html =3D=3D=3D=3D=3D "Formal" format =3D=3D=3D=3D=3D Each entry is composed of 2 parts: "#"-prefixed explanation block and list of "${CATEGORY}/${PN}" packages. Entries are separated when a new explanation block starts (meaning first "#"-prefixed line after packages list). You may add newlines between packages in packages list. The first line of the "#"-prefixed explanation block must be of the format "${AUTHOR_NAME} <${EMAIL}> (${SINGLE_DATE})" when the date is of format YYYY-MM-DD, in UTC timezone. If this is a last-rite message, the last line must list the last-rite last date (removal date) and the last-rite bug number. You can also list other bugs relevant to the last-rite. So I think a format of: "Removal on ${REMOVAL_DATE}. Bug #NNNNNN, #NNNNNN." Where the bug list is comma and space separated, we have at least one space (" +" regex) between the removal date and bug list, and the date is of YYYY-MM-DD format. I prefer this line is separate (and not continuous of prefix message text= ). The explanation block itself can reference bugs, by matching the regex "[Bb]ugs? #\d+(, +#\d+)*" (For example: "bug #713106, #753134"). I think this is quite a simple one, but powerful enough for most. Lines with single newline between them (so no blank line between them) are considered as single paragraph continuum. If you want to start new paragraph, leave a blank line (still prefixed with #) - think similar to markdown. A line matching the last-rite line is always it's own paragraph= =2E =3D=3D=3D=3D=3D=3D=3D=3D=3D Example =3D=3D=3D=3D=3D=3D=3D=3D=3D After all of those rambling, here is an example (it will result in 3 paragraphs, 2 explanation and 1 last-rite finish): # 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. Bug #667687, #667689. dev-lang/python =3D=3D=3D=3D Call for comments =3D=3D=3D=3D So how does it sound? I know it is easy to try to limit the syntax for me (since I"ll need to implement parsing of it), but I think this format above matches most of the currently used once, and the one created by `pkgdev mask`. But i needed, I'm open to improve it by comments. Should it be a GLEP, I don't think so? But I'm unsure about it. We do need to document it (for example header of that exact file). --=20 Arthur Zamarin arthurzam@gentoo.org Gentoo Linux developer (Python, pkgcore stack, Arch Teams, GURU) --------------pUSBHvcD0ZYRkE4PAgc0AVbR-- --------------mYjePsKsXg7eSb7niywg0r0F 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/axFlFuH2ptjtO5EAqCvUD0SBQQFAmUMnBUACgkQAqCvUD0S BQSdwgf+LPbufYu3qzGDx0XXTnCdu9CGLpD+WbqeoYesvaN0MzTPDKaWjv/liAMs jTy8oxIJ+TyDCcguVgmj1LC2We5FCHvEzdvBbEUX/RWyfj/pQvq+vnOTUNVILSdZ bd/jnjHhhVqNeTjwoDo2pa1+j5LLd3/1WyJgaEyctQafz+tYXRbfDSTsP0EsYaEu m1yra9ovySGZvvBPbukmj8q/pYZHB6CybOXQ5AZ0p/PYI2BTm4rO7ZGqds1wzLXX PyF0b+w6U0S4wc9Ue0TneKdtBSmfSQPls8RQz5zZSk+hi4JucbyO/4Rz1M8Mywt1 5HVYt8yduVsHf0BRy4zo17b31Vogpg== =4oc+ -----END PGP SIGNATURE----- --------------mYjePsKsXg7eSb7niywg0r0F--