From: Michal Privoznik <mprivozn@redhat.com>

Introduced in v10.5.0-rc1~52, qemu and lxc hook scripts are
executed with additional argument: shutoff reason. But wording of
our docs make it looks like it's been that way forever. Make it
clear this is `recent` feature.

Resolves: https://gitlab.com/libvirt/libvirt/-/issues/766
Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
---
 docs/hooks.rst | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/docs/hooks.rst b/docs/hooks.rst
index 48128ba3d8..b363f51da1 100644
--- a/docs/hooks.rst
+++ b/docs/hooks.rst
@@ -211,7 +211,9 @@ operation. There is no specific operation to indicate a "restart" is occurring.
       /etc/libvirt/hooks/qemu guest_name stopped end -
 
    Then, after libvirt has released all resources, the hook is called again,
-   :since:`since 0.9.0`, to allow any additional resource cleanup:
+   :since:`since 0.9.0`, to allow any additional resource cleanup
+   (:since:`since 10.5.0` there's additional argument ``shutoff-reason`` passed
+   to the hook):
 
    ::
 
@@ -331,7 +333,9 @@ operation. There is no specific operation to indicate a "restart" is occurring.
       /etc/libvirt/hooks/lxc guest_name stopped end -
 
    Then, after libvirt has released all resources, the hook is called again,
-   :since:`since 0.9.0`, to allow any additional resource cleanup:
+   :since:`since 0.9.0`, to allow any additional resource cleanup
+   (:since:`since 10.5.0` there's additional argument ``shutoff-reason`` passed
+   to the hook):
 
    ::
 
-- 
2.49.0

On Mon, May 05, 2025 at 10:54:41 +0200, Michal Privoznik via Devel wrote:
> From: Michal Privoznik <mprivozn@redhat.com>
> 
> Introduced in v10.5.0-rc1~52, qemu and lxc hook scripts are
> executed with additional argument: shutoff reason. But wording of
> our docs make it looks like it's been that way forever. Make it
> clear this is `recent` feature.
> 
> Resolves: https://gitlab.com/libvirt/libvirt/-/issues/766
> Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
> ---
>  docs/hooks.rst | 8 ++++++--
>  1 file changed, 6 insertions(+), 2 deletions(-)
> 
> diff --git a/docs/hooks.rst b/docs/hooks.rst
> index 48128ba3d8..b363f51da1 100644
> --- a/docs/hooks.rst
> +++ b/docs/hooks.rst
> @@ -211,7 +211,9 @@ operation. There is no specific operation to indicate a "restart" is occurring.
>        /etc/libvirt/hooks/qemu guest_name stopped end -
>  
>     Then, after libvirt has released all resources, the hook is called again,
> -   :since:`since 0.9.0`, to allow any additional resource cleanup:
> +   :since:`since 0.9.0`, to allow any additional resource cleanup
> +   (:since:`since 10.5.0` there's additional argument ``shutoff-reason`` passed
> +   to the hook):

I think we should also document what happened before the additional
argument was passed:

+   :since:`since 0.9.0`, to allow any additional resource cleanup.
+   The ``shutoff-reason`` argument (:since:`since 10.5.0`; before that
+   '-' was passed instead) provides the reason for the shutdown of
+   the domain.

>  
>     ::
>  
> @@ -331,7 +333,9 @@ operation. There is no specific operation to indicate a "restart" is occurring.
>        /etc/libvirt/hooks/lxc guest_name stopped end -
>  
>     Then, after libvirt has released all resources, the hook is called again,
> -   :since:`since 0.9.0`, to allow any additional resource cleanup:
> +   :since:`since 0.9.0`, to allow any additional resource cleanup
> +   (:since:`since 10.5.0` there's additional argument ``shutoff-reason`` passed
> +   to the hook):

But this is better than nothing so regardless of my suggestion:

Reviewed-by: Peter Krempa <pkrempa@redhat.com>