Packaging: Improve rpm scriptlet / deb maintainer script docs

Document all scripts, and update deb docs to better describe
when various args might be used and add some missing variants.

Author: cognifloyd

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

@@ -2,3 +2,18 @@
 # 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,5 +1,11 @@
 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

packaging/rpm/scripts/post-remove.sh

@@ -1,5 +1,11 @@
 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

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

@@ -1,5 +1,11 @@
 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