From fa8d40111736d1867d075b44da49d8dbb80af143 Mon Sep 17 00:00:00 2001
From: Caleb Maclennan <caleb@alerque.com>
Date: Thu, 14 Dec 2023 15:04:33 +0300
Subject: [PATCH 1/3] feat(packages): Add package to reset some defaults
 similar to previous releases

---
 packages/retrograde/init.lua | 48 ++++++++++++++++++++++++++++++++++++
 1 file changed, 48 insertions(+)
 create mode 100644 packages/retrograde/init.lua

diff --git a/packages/retrograde/init.lua b/packages/retrograde/init.lua
new file mode 100644
index 000000000..442d3958d
--- /dev/null
+++ b/packages/retrograde/init.lua
@@ -0,0 +1,48 @@
+local base = require("packages.base")
+
+local package = pl.class(base)
+package._name = "retrograde"
+
+local semver = require("semver")
+
+local semver_descending = function (a, b)
+   a, b = semver(a), semver(b)
+   return a > b
+end
+
+-- Default settings that have gone out of fashion
+package.default_settings = {
+}
+
+function package:_init (options)
+  base._init(self, options)
+  self:defaults(options.target)
+end
+
+function package:defaults (target)
+  target = semver(target and target or SILE.version)
+  local target_hit = false
+  for version, settings in pl.tablex.sort(self.default_settings, semver_descending) do
+     for parameter, value in pairs(settings) do
+        SILE.settings:set(parameter, value, true)
+     end
+     if target_hit then break end
+     if semver(version) <= target then target_hit = true end
+  end
+end
+
+function package:registerCommands ()
+
+  self:registerCommand("defaults", function (options, content)
+     if content then
+        SILE.settings:temporarily(function ()
+           self:defaults(options.target)
+        end)
+     else
+        self:defaults(options.target)
+     end
+  end)
+
+end
+
+return package

From fc80d94d21ce6263f1d98eb12b57faff84eebabc Mon Sep 17 00:00:00 2001
From: Caleb Maclennan <caleb@alerque.com>
Date: Thu, 14 Dec 2023 15:04:33 +0300
Subject: [PATCH 2/3] docs(manual): Add documentation for now defaults package

---
 documentation/c05-packages.sil |  4 ++++
 packages/retrograde/init.lua   | 31 +++++++++++++++++++++++++++++++
 2 files changed, 35 insertions(+)

diff --git a/documentation/c05-packages.sil b/documentation/c05-packages.sil
index b3f6089a4..df4c4037c 100644
--- a/documentation/c05-packages.sil
+++ b/documentation/c05-packages.sil
@@ -274,6 +274,10 @@ This section introduces packages that could not fit in another category.
 \status:low
 \package-documentation{ifattop}
 
+\subsection{retrograde}
+\status:high
+\package-documentation{retrograde}
+
 \section{Frames and page layouts}
 
 As we mentioned in the first chapter, SILE uses frames as an indication of where to put text onto
diff --git a/packages/retrograde/init.lua b/packages/retrograde/init.lua
index 442d3958d..c6c2bb201 100644
--- a/packages/retrograde/init.lua
+++ b/packages/retrograde/init.lua
@@ -45,4 +45,35 @@ function package:registerCommands ()
 
 end
 
+local doctarget = "v" .. tostring(semver(SILE.version))
+package.documentation = ([[
+\begin{document}
+
+From time to time, the default behavior of a function or value of a setting in SILE might change with a new release.
+If these changes are expected to cause document reflows they will be noted in release notes as breaking changes.
+That generally means old documents will have to be updated to keep rending the same way.
+On a best-effort basis (not a guarantee) this package tries to restore earlier default behaviors and settings.
+
+For settings this is relatively simple.
+You just set the old default value explicitly in your document or project.
+But first, knowing what those are requires a careful reading of the release notes.
+Then you have to chase down the incantations to set the old values.
+This package tries to restore as many previous setting values as possible to make old documents render like they would have in previous releases without changing the documents themselves (beyond loading this package).
+
+For functions things are a little more complex, but for as many cases as possible we'll try to allow swapping old versions of code.
+
+None of this is a guarantee that your old document will be stable in new versions of SILE.
+All of this is a danger zone.
+
+From inside a document, use \autodoc:command{\use[module=packages.retrograde,target=%s]} to load features from SILE %s.
+
+This can also be triggered from the command line with no changes to a document:
+
+\begin{autodoc:codeblock}
+$ sile -u 'packages.retrograde[target=%s]'
+\end{autodoc:codeblock}
+
+\end{document}
+]]):format(doctarget, doctarget, doctarget)
+
 return package

From 90dfee0ac76189e242eaaa35de68c39a23c92177 Mon Sep 17 00:00:00 2001
From: Caleb Maclennan <caleb@alerque.com>
Date: Thu, 14 Dec 2023 15:04:33 +0300
Subject: [PATCH 3/3] chore(packages): Add relevant debug output to defaults
 package

---
 packages/retrograde/init.lua | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/packages/retrograde/init.lua b/packages/retrograde/init.lua
index c6c2bb201..1ff4fd023 100644
--- a/packages/retrograde/init.lua
+++ b/packages/retrograde/init.lua
@@ -23,11 +23,13 @@ function package:defaults (target)
   target = semver(target and target or SILE.version)
   local target_hit = false
   for version, settings in pl.tablex.sort(self.default_settings, semver_descending) do
+     version = semver(version)
      for parameter, value in pairs(settings) do
+        SU.debug("defaults", ("Resetting '%s' to '%s' as it was prior to v%s"):format(parameter, tostring(value), version))
         SILE.settings:set(parameter, value, true)
      end
      if target_hit then break end
-     if semver(version) <= target then target_hit = true end
+     if version <= target then target_hit = true end
   end
 end