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

Hi All,

Have we reached a decision on this?  Got a case now where this would be 
useful.

Kind regards,
Jaco

On 2026/06/01 11:21, 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/".
>
>
> 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?
>
>