Re: [RFC] Putting extra package maintenance in maint/ subdirs

A Schenck <[email protected]> Sat, 6 Jun 2026 14:09:07 -0500
Newsgroups	gmane.linux.gentoo.devel
Message-ID	<PH7P223MB08794B566B1654B00588C9299D1E2@PH7P223MB0879.NAMP223.PROD.OUTLOOK.COM>
On 6/1/26 4:21 AM, Michał Górny wrote:
> Hello,
> 
> TL;DR: I'd like to propose that we allow a new "maint/" subdir in
> package directory where maintenance scripts (plus docs and other data
> files) can be placed rather than in "files/".
> 
As a (barely) maintainer of an application (app-portage/kuroo) that 
parses the gentoo tree, this proposal brings some slight concerns to 
mind. tl;dr: how about something under the already pre-existing 
'metadata' top level directory described by PMS [0] instead of inside 
the package directory?>
> Motivation
> ==========
> 
> Right now we don't have a single standard way of sharing package
> maintenance scripts, snippets, notes and docs.  Depending on the package
> in question, they can be found in one or more of:
> 
> - files/ directory
For kuroo at least, extra stuff under files/ is no problem because that 
only applies to the lower level package manager that actually runs 
ebuild phases.> - "unused" functions or comments in ebuilds
Similarly not a concern because the PM is what runs the ebuild phases> - 
Gentoo wiki pages
> - additional packages (e.g. app-portage/mgorny-dev-scripts)
> - local scripts on the maintainer's computer
> - somewhere in ~/.bash_history
> 
> Besides the specific disadvantages of some of these options, notably the
> risk of losing them, it makes it hard for anyone else to take
> maintenance over.  For packages maintained by projects, such as
> Distribution Kernels or LLVM, you can at least guess there could some
> (not necessarily up-to-date instructions) on the project pages.  For
> individually maintained packages, the best you can do is ask the former
> maintainer, hoping they're still reachable and they still remember.
> 
> 
> Proposal
> ========
> 
> We had a little discussion about possible options in #gentoo-qa, and it
> seems that the best suggestion was to create a new "maint/" subdirectory
> in the package directory.  This directory wouldn't be accessible to
> ebuilds themselves, it wouldn't be subject to QA checks (so pkgcheck
> won't complain about executable bits), and it may be omitted from
> repo/sync and rsync distribution (if anyone cares to implement that).
> You could place helper scripts there, a README file and/or other
> maintenace-oriented docs.
Personally this wouldn't be a problem if it was excluded from rsync 
before a maint/ directory was added because it wouldn't ever appear in 
the tree that kuroo parses.>
> Unless I'm missing something, backwards compatibility shouldn't be a
> problem since the extra directory will be ignored by tools.  QA tools
> such as pkgcheck will have to be updated not to complain about it,
> though.
Here's the rub, this definitely "should" be fine if everything was 
written to and kept up-to-date with PMS. Unfortunately kuroo dates back 
to before PMS and has historically made some assumptions that makes it 
rather brittle to changes in tree and file structure. Rewriting all the 
parsing code to fully conform too spec is a goal, but its pretty far 
away. The potential problem with this is that its another thing in an 
area (the package directory) that has a specific set of named entries 
and then arbitrary number of ebuilds. Referring to PMS section 4.3 [1] 
we have 'metadata.xml', 'ChangeLog', 'Manifest', 'files' directory which 
are all optional, and 'zero or more ebuilds'. A naïve parser would list 
all the items, ignore the specific named things it doesn't want, then 
try to treat everything else as an ebuild.
To be fair, this is somewhat of a straw man argument after reading 
through kuroo code which ignores directories entirely, but PMS already 
has another place for this kind of thing that isn't part of actual 
packages themselves, but a level above relating to managing those 
packages in gentoo:>
> 
> Open issues
> ===========
> 
> The "maint/" directory covers per-package scripts.  I don't have a good
> idea how to cover scripts that would be shared across a larger group of
> packages -- perhaps we could just keep them in one of the packages (say,
> llvm-core/llvm) or perhaps we should have another top-level
> "maint/{project}" directory structure.
That location is top level 'metadata' directory [0]! Which "contains 
various repository-level metadata that are not contained in 
'profiles/'." To my mind, this would be an ideal place for package 
maintenance things, which shouldn't ever be considered by the package 
manager itself, relates to how developers manage packages in the 
repository, and can be related to one or more package, where choosing 
one arbitrary "main" package directory to hold the proposed 'maint/' dir 
is awkward, and PMS explicitly forbids anything else in categories [2]: 
"Additional directories that are not for a package may /not/ be present, 
to avoid conflicts with package name directories".
If there is a concern that this is less discoverable than a 'maint/' 
directory inside the package directory, a comment saying e.g. "there are 
maintenance helper scripts in 'metadata/llvm'" in the ebuild should be 
pretty obvious to anyone looking at them, or an element / attribute 
could be added to metadata.xml, though that would presumably require 
updating GLEP 68.
Having a top level 'maint/{project}' directory structure feels 
extraneous when the vast majority of people and tools won't care 
                   about it. e.g. `ls /usr/portage/ |grep -v '-v'` shows:
```
distfiles
eclass
header.txt
licenses
Manifest
Manifest.files.gz
metadata
packages
profiles
scripts
skel.ebuild
skel.metadata.xml
virtual
```
This install has been carried forward since default PORTDIR was 
/usr/portage and distfiles and packages were under there hence those 
things, but that's already a lot of things to --ignore when grep-ing or 
find-ing under PORTDIR. Adding 'maint/' just makes that worse. The 
'scripts' directory is not described in PMS and the name sounds like it 
could hold package management scripts, though it currently only has 
'bootstrap.sh'.>
> 
> Rejected ideas
> ==============
> 
> The "obvious" option would be to just keep these scripts in "files/".
> However, this makes it hard to distinguish them from real files, and
> requires exemptions when we're checking for stale files.
> 
> My original idea was to add extra logic to ebuild, so that it could be
> executed directly.  However, that's kinda messy, and implies duplication
> across multiple versions.
> 
> 
> WDYT?
> 
> 
Anyways, that's just the overly verbose opinion of one slacker who 
hasn't even gone through the trouble of becoming a proper gentoo 
developer. Feel free to ignore it.

Cheers,
-A

0: https://projects.gentoo.org/pms/9/pms.html#the-metadata-directory or 
https://projects.gentoo.org/pms/9/pms.html#x1-40001x4.7
1: https://projects.gentoo.org/pms/9/pms.html#package-directories or 
https://projects.gentoo.org/pms/8/pms.html#x1-310004.3
2: https://projects.gentoo.org/pms/9/pms.html#category-directories or 
https://projects.gentoo.org/pms/8/pms.html#x1-300004.2

-- 
Attached is my PGP public key.
Primary key fingerprint: C334 A85F 5B84 0061 2DF9 7310 6E37 4F22 EB0C 3D3A

If you have a PGP key (and a minute to spare)
please send it in reply to this email.

If you have no idea what PGP is, feel free
to ignore all this gobbledegook.
OpenPGP_0x6E374F22EB0C3D3A.asc (application/pgp-keys, 3.5 KB)
OpenPGP_signature.asc (application/pgp-signature, 495 B)