public inbox for gentoo-dev@lists.gentoo.org
 help / color / mirror / Atom feed
* [gentoo-dev] Standard parsable format for profiles/package.mask file
@ 2023-09-21 19:40 Arthur Zamarin
  2023-09-21 21:09 ` [gentoo-dev] " Florian Schmaus
                   ` (4 more replies)
  0 siblings, 5 replies; 32+ messages in thread
From: Arthur Zamarin @ 2023-09-21 19:40 UTC (permalink / raw
  To: gentoo-dev


[-- Attachment #1.1: Type: text/plain, Size: 4072 bytes --]

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

===== "Formal" format =====

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.

========= Example =========

After all of those rambling, here is an example (it will result in 3
paragraphs, 2 explanation and 1 last-rite finish):

# 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.  Bug #667687, #667689.
dev-lang/python

==== Call for comments ====

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).


-- 
Arthur Zamarin
arthurzam@gentoo.org
Gentoo Linux developer (Python, pkgcore stack, Arch Teams, GURU)

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 488 bytes --]

^ permalink raw reply	[flat|nested] 32+ messages in thread

end of thread, other threads:[~2023-09-26  1:29 UTC | newest]

Thread overview: 32+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2023-09-21 19:40 [gentoo-dev] Standard parsable format for profiles/package.mask file Arthur Zamarin
2023-09-21 21:09 ` [gentoo-dev] " Florian Schmaus
2023-09-21 21:36   ` Ulrich Mueller
2023-09-21 21:48     ` Sam James
2023-09-22  6:39       ` Florian Schmaus
2023-09-22  6:53         ` Florian Schmaus
2023-09-22  9:46         ` Ulrich Mueller
2023-09-22 11:51           ` Ulrich Mueller
2023-09-22 14:01             ` Sam James
2023-09-22 14:26               ` Alex Boag-Munroe
2023-09-22 14:36                 ` Sam James
2023-09-22 14:50                   ` Alex Boag-Munroe
2023-09-22 17:28                     ` Arthur Zamarin
2023-09-23 13:59                       ` Sam James
2023-09-23  7:02                     ` Ulrich Mueller
2023-09-23 13:54                       ` Sam James
2023-09-23 14:01                       ` Alex Boag-Munroe
2023-09-23 17:48                         ` Ulrich Mueller
2023-09-24 18:29   ` Jonas Stein
2023-09-21 21:22 ` [gentoo-dev] " Ulrich Mueller
2023-09-21 22:10   ` Tim Harder
2023-09-21 22:19     ` Sam James
2023-09-22  3:54   ` Oskari Pirhonen
2023-09-22 12:12   ` Arthur Zamarin
2023-09-22  3:59 ` Oskari Pirhonen
2023-09-22  9:21   ` Ulrich Mueller
2023-09-22  9:53     ` Arthur Zamarin
2023-09-22 11:16 ` [gentoo-dev] " Florian Schmaus
2023-09-22 11:23   ` Jaco Kroon
2023-09-24 18:40 ` Jonas Stein
2023-09-25 12:03   ` Ulrich Mueller
2023-09-26  1:29     ` Oskari Pirhonen

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox