Small refactoring of retention

Author: nlewo

cmd/run.go

@@ -79,7 +79,7 @@ var runCmd = &cobra.Command{
 		gcRootsDir := path.Join(cfg.StateDir, "gcroots")
 		broker := brokerPkg.New()
 		broker.Start()
-		store, err := storePkg.New(broker, storeFilename, gcRootsDir, cfg.Retention.MaxBootEntries, cfg.Retention.MaxDeploymentEntries)
+		store, err := storePkg.New(broker, storeFilename, gcRootsDir, cfg.Retention.KeepBootEntries, cfg.Retention.KeepDeploymentEntries)
 		if err != nil {
 			logrus.Error(err)
 			os.Exit(1)

docs/howtos.md

@@ -95,23 +95,30 @@ services.comin = {
 
 Please note this is currently not supported by for nix-darwin configurations.
 
-## Profile retention policy
-
-comin tracks deployments in order to manage system profiles. This
-allows to control the number of boot entries and the number of Nix
-store roots. It is then possible to control the size of the Nix store
-(by activating the `nix.gc.automatic` module).
-
-First of all, comin preserves the booted system in the boot entries menu.
-
-You can then control the number of boot entries and the number of
-previous deployments kept in the comin deployment history. Two
-configuration options allow to control the retention:
-
-- `retention.max_boot_entries`: the maximum number of last boot entries
-- `retention.max_deployment_entries`: the maximum number of last
-  deployment entries in the comin deployment history
-
+## Deployments and profiles retention policy
+
+comin tracks deployments in its persisent storage. It uses this list
+to add and remove system profiles which are consumed by bootloaders to install
+boot menu entries.
+
+The goal of the retention policy is to
+1. keep the currently booted system, in order to always be able to rollback on reboot
+2. keep the currently switched system
+3. keep a configuration quantity of successful deployments leading to a boot menu entries (typically, `boot` and `switch` deployments).
+   This is configuration thanks to `retention.keepBootEntries`
+4. keep a configuration quantity of deployments to provide an history to the user
+   This is configuration thanks to `retention.keepDeploymentEntries`
+
+Thanks to this retention policy, you could then enable the
+`nix.gc.automatic` module to automatically clean up your Nix store,
+while preserving a configurable gcroot history.
+
+Note that your bootloader entries shows one more entries than the ones
+listed by `comin deployment list`. This is currently a comin
+implementation limitation. Comin first creates a deployment, deploys it and
+if it has been successfully deployed, it can remove older deployments,
+accordingly to the retention policy. However, when it removes the
+deployment, it currently doesn't reinstall the bootloader.
 
 ## What happen on /var/lib/comin deletion
 
@@ -125,6 +132,6 @@ the consequencies:
   CVEs.
 - comin no longer knows the deployment history. On the next
   deployment, it would then no longer able to generate boot entries
-  for previous deployments. So, even if you delete the
+  for previous deployments. However, if you delete the
   `/var/lib/comin` directory, the current booted entry would still be
   present in the boot menu.

internal/types/types.go

@@ -56,8 +56,8 @@ type Confirmer struct {
 }
 
 type Retention struct {
-	MaxBootEntries       int `yaml:"max_boot_entries"`
-	MaxDeploymentEntries int `yaml:"max_deployment_entries"`
+	KeepBootEntries       int `yaml:"keep_boot_entries"`
+	KeepDeploymentEntries int `yaml:"keep_deployment_entries"`
 }
 
 type Configuration struct {

nix/module-options.nix

@@ -305,18 +305,18 @@ in {
         default = {};
         type = submodule {
           options = {
-            max_boot_entries = mkOption {
+            keep_boot_entries = mkOption {
               type = int;
               default = 2;
               description = ''
-                The maximum number of boot entries to keep. note that the booted system is always preserved in the boot menu.
+                The number of boot entries to keep.
               '';
             };
-            max_deployment_entries = mkOption {
+            keep_deployment_entries = mkOption {
               type = int;
-              default = 5;
+              default = 3;
               description = ''
-                The maximum number of deployments entries to keep.
+                The number of deployments to keep.
               '';
             };
           };