[bug#76910] [PATCH v3 5/5] gnu: Add hyprland plugin maintainer note

[Andrew Wong]

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