linamh/AGENTS.md

Overlay Update Rules

Read this file before update rounds. This repository is a Gentoo overlay with intentional local packages. Do not remove or replace packages only because Gentoo has a newer version.

General Workflow

• Compare overlay package directories against /var/db/repos/gentoo first.
• For packages that exist in Gentoo, remove the local copy only if it has no local patches, no compatibility purpose, and no user-stated reason to stay.
• Keep old versions if they are intentionally present because Gentoo dropped the package, an old ABI is needed, or local patches are required.
• Regenerate Manifest after every ebuild, patch, desktop file, or distfile change.
• Prefer testing with ebuild <pkg>.ebuild clean prepare at minimum, and clean install when the package can be installed into an image without root ownership issues.
• Do not revert unrelated dirty tree changes.

Packages To Keep Intentionally

• Keep the Qt5 ebuild set local as a complete set.
• Keep Win4Lin packages and old source packages unless explicitly told otherwise.
• Keep local packages that are present for custom patches, for example net-libs/c-client and sys-fs/jfsutils.
• dev-lang/tauthon is a Python 2.7 bridge, not a normal Gentoo Python target. Do not try to make distutils-r1 or python-r1 modules use it through PYTHON_COMPAT=python2_7; patch those ebuilds manually when needed.

Update Checking

• Do not rely blindly on a repository's global latest release if one upstream repository publishes multiple applications.
• For mkrueger/icy_tools, inspect releases per asset:
  • app-text/icy-draw: newest icy_draw_linux_<version>.zip
  • media-gfx/icy-view: newest icy_view_linux_<version>.zip
  • net-misc/icy-term: newest icy_term_linux_<version>.zip
• app-emulation/remotebox versions track VirtualBox compatibility. They must be slotted by VirtualBox series and must not install colliding unversioned files.
  • RemoteBox 3.6 is for VirtualBox 7.1 and installs remotebox-7.1.
  • RemoteBox 3.7 is for VirtualBox 7.2 and installs remotebox-7.2.
  • Use separate share directories, desktop files, and icon names per slot.
• For binary vendor packages, verify the downloaded archive/deb/rpm structure before assuming the old src_install still works.
• For GitHub projects, inspect the release assets, not just tag names, when the asset filename contains channel, app name, architecture, or date suffixes.

Portage Preference

• The local overlay should have higher priority than third-party overlays when versions are equal.
• Avoid pulling packages from broad third-party overlays just to satisfy a single old dependency; prefer local minimal bridge packages where practical.

Known Verification Notes

• Direct ebuild install as a normal user can fail on chown into the Portage image. Treat that as a test-environment limitation when prepare and install paths are otherwise correct; verify with a real emerge if needed.
• pkgcheck --net no can report false DeadUrl results for network checks. Distfile fetch/manifest success is stronger evidence for the changed package.