Subject: [PATCH v3 5/5] gnu: Add hyprland plugin maintainer note

From: Andrew Wong <[email-masked]>
Date: Tue, 1 Apr 2025 03:34:42 -0400

Change-Id: I971940d515b1820532abbc31754d31d6f2efd515
---
 gnu/packages/wm.scm | 27 +++++++++++++++++++++++++++
 1 file changed, 27 insertions(+)

diff --git a/gnu/packages/wm.scm b/gnu/packages/wm.scm
index 537150e138..03ccc0dce6 100644
--- a/gnu/packages/wm.scm
+++ b/gnu/packages/wm.scm
@@ -447,6 +447,33 @@ (define-public hyprland
      `((upstream-name . "source")))
     (license license:bsd-3)))
 
+
+;; READ THIS regarding Hyprland plugin versioning
+;;
+;; Each Hyprland plugin contains a .toml file with an entry called `commit_pins'
+;; containing pairs of commit hashes. The first hash is Hyprland's commit hash, and
+;; the second hash is the hash of the plugin repository which hyprpm would switch to
+;; before compiling the plugin[1]. Therefore, to remain consistent with hyprpm, when
+;; upgrading a plugin, maintainers should check its .toml file and use the hash
+;; corresponding to the packaged Hyprland version. If Hyprland's packaged commit is
+;; not listed, packagers should use the latest working commit. For plugins that lack
+;; their own version numbers, we will use git-version, with the newest supported
+;; Hyprland version as the VERSION argument.
+;;
+;; A flaw with this way of doing things is that the correct version of a plugin will
+;; not automatically be built if a transformation is used to select a different
+;; version of Hyprland from what is packaged, or if Hyprland is updated without its
+;; plugins. However, with the rapid pace (as of 1 Apr 2025) of Hyprland and related
+;; softwares, we can reasonably hope that soon, either A) hyprpm will develop enough
+;; to become usable as a Guix-managed build tool, or B) hyprpm will become obsolete
+;; by the introduction of a stable, versioned Hyprland API.
+;;
+;; You can safely test plugins by launching hyprland from a shell (wayland sessions
+;; can run within each other) and loading the plugin into it using hyprctl's
+;; '--instance' option and 'plugin load' command.
+;;
+;; [1] https://wiki.hyprland.org/Plugins/Development/Plugin-Guidelines/#commit-pins
+
 (define hyprland-plugin
   (lambda (plugin-name plugin-provision)
     "Generate a packaged plugin from Hyprland's official plugin repository."
-- 
2.49.0