[RFC] Putting extra package maintenance in maint/ subdirs

Michał Górny <[email protected]> Mon, 01 Jun 2026 11:21:37 +0200
Newsgroups	gmane.linux.gentoo.devel
Organization	Gentoo
Message-ID	<[email protected]>
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/".


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
- "unused" functions or comments in ebuilds
- 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.

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.


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.


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?


-- 
Best regards,
Michał Górny
signature.asc (application/pgp-signature, 293 B)