upgrade: Stabilize deployment staging

We're waaay overdue for this, it's been the default
in rpm-ostree for years, and solves several important bugs
around not capturing `/etc` while things are running.

Also, `ostree admin upgrade --stage` (should) become idempotent.

Closes: https://github.com/ostreedev/ostree/issues/2389

src/libostree/ostree-sysroot-upgrader.c

@@ -646,7 +646,8 @@ ostree_sysroot_upgrader_deploy (OstreeSysrootUpgrader  *self,
   g_autoptr(OstreeDeployment) new_deployment = NULL;
 
   /* Experimental flag to enable staging */
-  if (getenv ("OSTREE_EX_STAGE_DEPLOYMENTS"))
+  gboolean stage = (self->flags & OSTREE_SYSROOT_UPGRADER_FLAGS_STAGE) > 0 || getenv ("OSTREE_EX_STAGE_DEPLOYMENTS") != NULL;
+  if (stage)
     {
       if (!ostree_sysroot_stage_tree (self->sysroot, self->osname,
                                       self->new_revision,
@@ -688,6 +689,7 @@ ostree_sysroot_upgrader_flags_get_type (void)
     {
       static const GFlagsValue values[] = {
         { OSTREE_SYSROOT_UPGRADER_FLAGS_IGNORE_UNCONFIGURED, "OSTREE_SYSROOT_UPGRADER_FLAGS_IGNORE_UNCONFIGURED", "ignore-unconfigured" },
+        { OSTREE_SYSROOT_UPGRADER_FLAGS_STAGE, "OSTREE_SYSROOT_UPGRADER_FLAGS_STAGE", "stage" },
         { 0, NULL, NULL }
       };
       GType g_define_type_id =

src/libostree/ostree-sysroot-upgrader.h

@@ -35,12 +35,15 @@ G_BEGIN_DECLS
  * OstreeSysrootUpgraderFlags:
  * @OSTREE_SYSROOT_UPGRADER_FLAGS_NONE: No options
  * @OSTREE_SYSROOT_UPGRADER_FLAGS_IGNORE_UNCONFIGURED: Do not error if the origin has an unconfigured-state key
+ * @OSTREE_SYSROOT_UPGRADER_FLAGS_STAGE: Enable "staging" (finalization at shutdown); recommended
+ *    (Since: 2021.4)
  *
  * Flags controlling operation of an #OstreeSysrootUpgrader.
  */
 typedef enum {
   OSTREE_SYSROOT_UPGRADER_FLAGS_NONE = (1 << 0),
   OSTREE_SYSROOT_UPGRADER_FLAGS_IGNORE_UNCONFIGURED = (1 << 1),
+  OSTREE_SYSROOT_UPGRADER_FLAGS_STAGE = (1 << 2),
 } OstreeSysrootUpgraderFlags;
 
 _OSTREE_PUBLIC