Packaging: Improve rpm scriptlet / deb maintainer script docs

CHANGELOG.rst

@@ -79,7 +79,7 @@ Added
   to pants' use of PEX lockfiles. This is not a user-facing addition.
   #6118 #6141 #6133 #6120 #6181 #6183 #6200 #6237 #6229 #6240 #6241 #6244 #6251 #6253
   #6254 #6258 #6259 #6260 #6269 #6275 #6279 #6278 #6282 #6283 #6273 #6287 #6306 #6307
-  #6311 #6314
+  #6311 #6314 #6315
   Contributed by @cognifloyd
 * Build of ST2 EL9 packages #6153
   Contributed by @amanda11

packaging/deb/scripts/post-install.sh

@@ -6,16 +6,28 @@
 set -e
 
 # summary of how this script can be called:
-#        * <postinst> `configure' <most-recently-configured-version>
-#        * <old-postinst> `abort-upgrade' <new version>
-#        * <conflictor's-postinst> `abort-remove' `in-favour' <package>
-#          <new-version>
-#        * <postinst> `abort-remove'
-#        * <deconfigured's-postinst> `abort-deconfigure' `in-favour'
-#          <failed-install-package> <version> `removing'
-#          <conflicting-package> <version>
-# for details, see http://www.debian.org/doc/debian-policy/ or
-# the debian-policy package
+#     <new-postinst> configure
+#         on fresh install
+#     <new-postinst> configure <most-recently-configured-version>
+#         on upgrade OR on install after pkg removal without purging conf files
+#     <old-postinst> abort-upgrade <new version>
+#         on upgrade failed (after failure of prerm, preinst, postrm)
+#     <conflictor's-postinst> abort-remove in-favour <package> <new-version>
+#         on removal due to conflict with other package
+#     <postinst> abort-remove
+#         on removal (after failure of prerm)
+#     <deconfigured's-postinst> abort-deconfigure in-favour
+#             <failed-install-package> <version>
+#             [ removing <conflicting-package> <version> ]
+#         on removal due to breaks/conflict with other package (if --auto-deconfigure)
+#     <postinst> triggered <trigger-name> [<trigger-name> ...]
+#         when a trigger we've registered interest in fires,
+#         such as when /usr/bin/python3.9 (or similar) gets updated,
+#         allowing this script to rebuild the venv.
+# https://www.debian.org/doc/debian-policy/ch-maintainerscripts.html
+# https://www.mankier.com/5/deb-postinst
+# https://www.mankier.com/5/deb-triggers
+# https://stackoverflow.com/questions/15276535/dpkg-how-to-use-trigger
 
 case "$1" in
     configure)

packaging/deb/scripts/post-remove.sh

@@ -6,17 +6,23 @@
 set -e
 
 # summary of how this script can be called:
-#        * <postrm> `remove'
-#        * <postrm> `purge'
-#        * <old-postrm> `upgrade' <new-version>
-#        * <new-postrm> `failed-upgrade' <old-version>
-#        * <new-postrm> `abort-install'
-#        * <new-postrm> `abort-install' <old-version>
-#        * <new-postrm> `abort-upgrade' <old-version>
-#        * <disappearer's-postrm> `disappear' <overwriter>
-#          <overwriter-version>
-# for details, see http://www.debian.org/doc/debian-policy/ or
-# the debian-policy package
+#     <postrm> remove
+#         on remove or remove+purge
+#     <postrm> purge
+#         on purge or remove+purge
+#     <old-postrm> upgrade <new-version>
+#         on upgrade
+#     <disappearer's-postrm> disappear <overwriter> <overwriter-version>
+#         on implicit removal (all package files replaced by another package)
+#     <new-postrm> abort-install
+#         on failed fresh install (after <preinst> failed)
+#     <new-postrm> abort-install <old-version> <new-version>
+#         on failed install after pkg removal w/o conf purge (and <preinst> failed)
+#     <new-postrm> failed-upgrade <old-version> <new-version>
+#         on upgrade failed (after <old-postrm> failed)
+#     <new-postrm> abort-upgrade <old-version> <new-version>
+#         on upgrade failed (after <new-preinst> or <old-postrm> failed)
+# https://www.debian.org/doc/debian-policy/ch-maintainerscripts.html
 
 purge_files() {
     # This -pkgsaved.disabled file might be left over from old (buggy) deb packages

packaging/deb/scripts/pre-install.sh

@@ -6,12 +6,15 @@
 set -e
 
 # summary of how this script can be called:
-#        * <new-preinst> `install'
-#        * <new-preinst> `install' <old-version>
-#        * <new-preinst> `upgrade' <old-version>
-#        * <old-preinst> `abort-upgrade' <new-version>
-# for details, see http://www.debian.org/doc/debian-policy/ or
-# the debian-policy package
+#     <new-preinst> install
+#         on fresh install
+#     <new-preinst> install <old-version> <new-version>
+#         on install after pkg removal without conf purge
+#     <new-preinst> upgrade <old-version> <new-version>
+#         on upgrade
+#     <old-preinst> abort-upgrade <new-version>
+#         on upgrade failed (after failure of postrm)
+# https://www.debian.org/doc/debian-policy/ch-maintainerscripts.html
 
 PACKS_GROUP=st2packs
 SYS_USER=stanley

packaging/deb/scripts/pre-remove.sh

@@ -0,0 +1,19 @@
+#!/bin/sh
+# prerm script for st2
+
+set -e
+
+# summary of how this script can be called:
+#     <new-prerm> remove
+#         on remove or remove+purge
+#     <old-prerm> upgrade <new-version>
+#         on upgrade
+#     <conflictor's-prerm> remove in-favour <package> <new-version>
+#         on removal due to conflict with other package
+#     <deconfigured's-prerm> deconfigure in-favour
+#             <package-being-installed> <version>
+#             [ removing <conflicting-package> <version> ]
+#         on removal due to breaks/conflict with other package (if --auto-deconfigure)
+#     <new-prerm> failed-upgrade <old-version> <new-version>
+#         on upgrade failed (after <old-prerm> failed)
+# https://www.debian.org/doc/debian-policy/ch-maintainerscripts.html

packaging/rpm/scripts/post-install.sh

@@ -1,4 +1,15 @@
 set -e
 
+# This %post scriptlet gets one argument, $1, the number of packages of
+# this name that will be left on the system when this script completes. So:
+#   * on install: $1 = 1
+#   * on upgrade: $1 > 1
+# https://docs.fedoraproject.org/en-US/packaging-guidelines/Scriptlets/#_syntax
+
+# from %post in st2-packages.git/packages/st2/rpm/st2.spec
+%service_post st2actionrunner st2api st2stream st2auth st2notifier st2workflowengine
+%service_post st2rulesengine st2timersengine st2sensorcontainer st2garbagecollector
+%service_post st2scheduler
+
 # make sure that our socket generators run
 systemctl daemon-reload >/dev/null 2>&1 || true

packaging/rpm/scripts/post-remove.sh

@@ -0,0 +1,17 @@
+set -e
+
+# This %postun scriptlet gets one argument, $1, the number of packages of
+# this name that will be left on the system when this script completes. So:
+#   * on upgrade:   $1 > 0
+#   * on uninstall: $1 = 0
+# https://docs.fedoraproject.org/en-US/packaging-guidelines/Scriptlets/#_syntax
+
+# from %postun in st2-packages.git/packages/st2/rpm/st2.spec
+%service_postun st2actionrunner %{worker_name} st2api st2stream st2auth st2notifier st2workflowengine
+%service_postun st2rulesengine st2timersengine st2sensorcontainer st2garbagecollector
+%service_postun st2scheduler
+
+# Remove st2 logrotate config, since there's no analog of apt-get purge available
+if [ $1 -eq 0 ]; then
+    rm -f /etc/logrotate.d/st2
+fi

packaging/rpm/scripts/pre-install.sh

@@ -1,5 +1,11 @@
 set -e
 
+# This %pre scriptlet gets one argument, $1, the number of packages of
+# this name that will be left on the system when this script completes. So:
+#   * on install: $1 = 1
+#   * on upgrade: $1 > 1
+# https://docs.fedoraproject.org/en-US/packaging-guidelines/Scriptlets/#_syntax
+
 PACKS_GROUP=%{packs_group}
 SYS_USER=%{stanley_user}
 ST2_USER=%{svc_user}

packaging/rpm/scripts/pre-remove.sh

@@ -0,0 +1,12 @@
+set -e
+
+# This %preun scriptlet gets one argument, $1, the number of packages of
+# this name that will be left on the system when this script completes. So:
+#   * on upgrade:   $1 > 0
+#   * on uninstall: $1 = 0
+# https://docs.fedoraproject.org/en-US/packaging-guidelines/Scriptlets/#_syntax
+
+# from %preun in st2-packages.git/packages/st2/rpm/st2.spec
+%service_preun st2actionrunner %{worker_name} st2api st2stream st2auth st2notifier st2workflowengine
+%service_preun st2rulesengine st2timersengine st2sensorcontainer st2garbagecollector
+%service_preun st2scheduler