Skip to content

AGENTS.md

Latest commit

 

History

History
64 lines (46 loc) · 5.13 KB

AGENTS.md

File metadata and controls

64 lines (46 loc) · 5.13 KB
Raw

Developer & Agent Guidelines for fedora-update

Welcome to fedora-update. This document outlines the architectural principles, design requirements, and development guidelines for this repository. All human contributors and AI agents working on this codebase must adhere to these rules.

🏛️ Project Architecture

fedora-update is a modular, lightweight, and robust maintenance suite and system tray monitor for Fedora Linux:

  • bin/fedora-update-cli: Interactive command-line update runner. Manages package updates (DNF & Flatpak), Secure Boot / MOK key validation, kernel module compilation (akmods), and initramfs regeneration (dracut).
  • lib/check_backend.sh: Lightweight background checker executed by systemd timer or triggered on-demand. Gathers DNF/Flatpak update counts, reboot requirements, Secure Boot state, and NVIDIA Flatpak GL runtime compatibility into /var/cache/fedora-update/status.json.
  • lib/fedora-update-tray: PyQt5 system tray indicator. Watches /var/cache/fedora-update/status.json, displays visual badges/notifications, manages language switching, and launches the CLI tool inside the user's terminal emulator.
  • lib/fedora_update_i18n.py: Central internationalization (i18n) engine supporting 20+ languages with automated system locale detection and user configuration override (~/.config/fedora-update/config.json).
  • locales/*.json: Multilingual JSON dictionaries.
  • systemd/ & polkit/: Systemd timer/service and Polkit rules allowing passwordless background cache refresh.
  • fedora-update.spec & build_rpm.sh: RPM spec definition and local/Copr build automation script.

🔒 Secure Boot & MOK Key Guidelines

  1. Silent when disabled: If Secure Boot is disabled (mokutil --sb-state does not report enabled), the application must run silently with zero MOK-related prompts or checks.
  2. Silent for non-NVIDIA / standard kernel: If Secure Boot is enabled on a system with an AMD or Intel GPU running an official Fedora kernel (kernel-core signed by Fedora), no kernel modules require out-of-tree signing. The application must remain completely silent.
  3. Targeted check for NVIDIA & Custom Kernels:
    • SCM/akmods uses /etc/pki/akmods/certs/public_key.der and /etc/pki/akmods/private/private_key.priv.
    • If Secure Boot is enabled AND (NVIDIA GPU is present OR a custom unsigned kernel is used):
      • Check if an active signing key exists and is enrolled in mokutil --list-enrolled.
      • If the key already exists and is enrolled, proceed silently without re-signing or prompting.
      • Only if the key is missing or unenrolled: prompt the user to generate (kmodgenca -a) and import (mokutil --import), providing clear instructions for the post-reboot MokManager blue screen.
  4. No arbitrary signing: Never sign files or trigger mokutil imports indiscriminately.

🍳 NVIDIA & Kernel Module Baking Rules

The "baking" logic into initramfs is a core selling point of fedora-update:

  1. Smart Trigger: Rebuilding kernel modules and initramfs must only be triggered if:
    • An NVIDIA GPU is present AND
    • New kernel package(s) were installed OR NVIDIA driver package(s) were upgraded.
  2. Differentiated Scope:
    • Kernel Update Only: If new kernel(s) were installed but the driver version remained constant, run akmods --force --kernel <new_kver> and dracut --force --kver <new_kver> only for the newly installed kernel(s).
    • NVIDIA Driver Update: If NVIDIA driver packages (akmod-nvidia, xorg-x11-drv-nvidia, nvidia-driver) were updated, run akmods --force --kernels all and dracut --regenerate-all --force across all installed kernels.
  3. Clean & Quiet Output:
    • Output must start with: Baking Nvidia kernel modules into initramfs for safe reboot...
    • Execution of akmods and dracut must run cleanly without standard output spam, capturing errors only if a command fails.
    • On completion: Nvidia kernel modules are baked and the system is ready for reboot.

💬 User Experience & CLI Prompts

  • Granular confirmation: Users must never experience unexpected auto-actions. Every major step (DNF upgrade, Flatpak update, MOK enrollment, system reboot) requires clear user confirmation prompts ([Y/n]).
  • No hardcoded text in CLI: All UI text must be routed through fedora_update_i18n.py using _("KEY") and backed by entries in locales/en.json.

📦 RPM Packaging & Copr Compatibility

  • Preserve rpkg Macros: fedora-update.spec must keep {{{ git_dir_pack }}} and {{{ git_dir_setup_macro }}} in the repository so remote Copr builds succeed.
  • Local Builds: build_rpm.sh replaces these macros only in a temporary buildroot during local compilation.
  • Cross-Distro Mirroring: build_rpm.sh mirrors the repository to /home/tux/SSD2/development/fedora-update for deployment alongside debian-update. Always verify 1:1 parity after building.
  • Instant Autostart: The %post scriptlet in fedora-update.spec should trigger autostart for active user sessions via systemctl --user -M <user>@ so the tray indicator launches without requiring a logout/login.