From 2290adc2ba5e5afa36e555a1099ec32d01e7ba29 Mon Sep 17 00:00:00 2001
From: Wayne Starr <me@racer159.com>
Date: Tue, 29 Apr 2025 10:31:56 -0600
Subject: [PATCH 1/2] ZEP-0026: Enhanced State Management

Signed-off-by: Wayne Starr <me@racer159.com>
---
 0026-enhanced-state-management/README.md | 241 +++++++++++++++++++++++
 0026-enhanced-state-management/zep.yaml  |  25 +++
 2 files changed, 266 insertions(+)
 create mode 100644 0026-enhanced-state-management/README.md
 create mode 100644 0026-enhanced-state-management/zep.yaml

diff --git a/0026-enhanced-state-management/README.md b/0026-enhanced-state-management/README.md
new file mode 100644
index 0000000..417724f
--- /dev/null
+++ b/0026-enhanced-state-management/README.md
@@ -0,0 +1,241 @@
+<!--
+**Note:** When your ZEP is complete, all of these comment blocks should be removed.
+
+To get started with this template:
+
+- [ ] **Create an issue in zarf-dev/proposals.**
+  When creating a proposal issue, complete all fields in that template. One of
+  the fields asks for a link to the ZEP, which you can leave blank until the ZEP
+  is filed. Then, go back and add the link.
+- [ ] **Make a copy of this template directory.**
+  Name it `NNNN-short-descriptive-title`, where `NNNN` is the issue number
+  (with no leading zeroes).
+- [ ] **Fill out as much of the zep.yaml file as you can.**
+  At minimum, complete the "Title", "Authors", "Status", and date-related fields.
+- [ ] **Fill out this file as best you can.**
+  Focus on the "Summary" and "Motivation" sections first. If you've already discussed
+  the idea with the Technical Steering Committee, this part should be easier.
+- [ ] **Create a PR for this ZEP.**
+  Assign it to members of the Technical Steering Committee who are sponsoring this process.
+- [ ] **Merge early and iterate.**
+  Don’t get bogged down in the details—focus on getting the goals clarified and the
+  ZEP merged quickly. You can fill in the specifics incrementally in later PRs.
+
+Just because a ZEP is merged doesn't mean it's complete or approved. Any ZEP marked
+as `provisional` is a working document and subject to change. You can mark unresolved
+sections like this:
+
+```
+<<[UNRESOLVED optional short context or usernames ]>>
+Stuff that is being argued.
+<<[/UNRESOLVED]>>
+```
+
+When editing ZEPs, aim for focused, single-topic PRs to keep discussions clear. If
+you disagree with a section, open a new PR with suggested changes.
+
+Each ZEP covers one "feature" or "enhancement" throughout its lifecycle. You don’t
+need a new ZEP for moving from beta to GA. If new details emerge, edit the existing
+ZEP. Once a feature is "implemented", major changes should go in new ZEPs.
+
+The latest instructions for this template can be found in [this repo](/NNNN-zep-template/README.md).
+
+**Note:** PRs to move a ZEP to `implementable`, or significant changes to an
+`implementable` ZEP, must be approved by all ZEP approvers. If an approver is no
+longer appropriate, updates to the list must be approved by the remaining approvers.
+-->
+
+# ZEP-NNNN: Your short, descriptive title
+
+<!--
+Keep the title short simple and descriptive. It should clearly convey what
+the ZEP is going to cover.
+-->
+
+<!--
+A table of contents helps reviewers quickly navigate the ZEP and highlights
+any additional information provided beyond the standard ZEP template.
+-->
+
+<!-- toc -->
+- [Summary](#summary)
+- [Motivation](#motivation)
+  - [Goals](#goals)
+  - [Non-Goals](#non-goals)
+- [Proposal](#proposal)
+  - [User Stories (Optional)](#user-stories-optional)
+    - [Story 1](#story-1)
+    - [Story 2](#story-2)
+  - [Risks and Mitigations](#risks-and-mitigations)
+- [Design Details](#design-details)
+  - [Test Plan](#test-plan)
+      - [Prerequisite testing updates](#prerequisite-testing-updates)
+      - [Unit tests](#unit-tests)
+      - [e2e tests](#e2e-tests)
+  - [Graduation Criteria](#graduation-criteria)
+  - [Upgrade / Downgrade Strategy](#upgrade--downgrade-strategy)
+  - [Version Skew Strategy](#version-skew-strategy)
+- [Implementation History](#implementation-history)
+- [Drawbacks](#drawbacks)
+- [Alternatives](#alternatives)
+- [Infrastructure Needed (Optional)](#infrastructure-needed-optional)
+<!-- /toc -->
+
+## Summary
+
+This ZEP proposes to improve Zarf's tracking of package and component state so that it can make smarter decisions about what to upgrade and what to remove.  This would add tracking of Kubernetes objects that were created by a Zarf deployment as well as including more history of previous Zarf deployments similar to Helm.
+
+## Motivation
+
+Currently there are a few issues that limit what you can do with Zarf due to the way Zarf manages its state:
+
+1. Zarf tracks packages _only_ by their package name meaning you cannot have two deployments of the same package in the same cluster
+1. If you force Zarf to install packages side by side (i.e. through the library) then you can only remove the last version of the package you installed
+1. If a package removes a component from one version to the next then Zarf will lose track of that component during an upgrade
+1. Zarf does not track the history of previous Zarf deployments giving less insight into what has been deployed in the past
+
+### Goals
+
+- Enable better tracking of resources created during a Zarf package deployment
+- Enable history of Zarf deployments to be tracked
+
+### Non-Goals
+
+- Usurp Helm's lifecycle management of charts/objects deployed by Zarf (i.e. rollback)
+
+## Proposal
+
+The proposed solution is to split Zarf secrets into one for each version of a package
+
+### User Stories (Optional)
+
+
+
+#### Story 1
+
+#### Story 2
+
+### Risks and Mitigations
+
+<!--
+What are the risks of this proposal, and how do we mitigate? Think broadly.
+For example, consider both security and how this will impact the larger
+Zarf ecosystem.
+
+How will security be reviewed, and by whom?
+
+How will UX be reviewed, and by whom?
+-->
+
+## Design Details
+
+<!--
+This section should contain enough information that the specifics of your
+change are understandable. This may include API specs (though not always
+required) or even code snippets. If there's any ambiguity about HOW your
+proposal will be implemented, this is the place to discuss that.
+-->
+
+### Test Plan
+
+<!--
+**Note:** *Not required until targeted at a release.*
+The goal is to ensure that we don't accept proposals with inadequate testing.
+
+All code is expected to have adequate tests (eventually with coverage
+expectations). Please adhere to the [Zarf testing guidelines][testing-guidelines]
+when drafting this test plan.
+
+[testing-guidelines]: https://docs.zarf.dev/contribute/testing/
+-->
+
+[ ] I/we understand the owners of the involved components may require updates to
+existing tests to make this code solid enough prior to committing the changes necessary
+to implement this proposal.
+
+### Graduation Criteria
+
+<!--
+**Note:** *Not required until you're targeting a release.*
+
+Define what needs to happen for this feature to move from alpha to beta to GA
+(General Availability). Focus on key signals or criteria that show the feature
+is ready for each stage.
+
+Consider the following stages when setting graduation criteria:
+- Alpha: Feature is behind a feature flag, basic tests in place.
+- Beta: Gather feedback from users, complete core features, add more tests.
+- GA: Prove real-world usage, complete rigorous testing, gather feedback.
+
+In general, features should wait at least two releases between Beta and GA to
+allow time for feedback. For features moving to GA, include conformance tests
+to ensure stability and compatibility.
+
+#### Deprecation
+If this feature will eventually be deprecated, plan for it:
+- Announce deprecation and support policy.
+- Wait at least two versions before fully removing it.
+-->
+
+### Upgrade / Downgrade Strategy
+
+<!--
+If applicable, how will the component be upgraded and downgraded? Make sure
+this is in the test plan.
+
+Consider the following in developing an upgrade/downgrade strategy for this
+proposal:
+- What changes (in invocations, configurations, API use, etc.) is an existing
+  package definition or deployment required to make on upgrade, in order to
+  maintain previous behavior?
+- What changes (in invocations, configurations, API use, etc.) is an existing
+  package definition or deployment required to make on upgrade, in order to
+  make use of the proposal?
+-->
+
+### Version Skew Strategy
+
+<!--
+If applicable, how will the component handle version skew with other
+components? What are the guarantees? Make sure this is in the test plan.
+
+Consider the following in developing a version skew strategy for this
+proposal:
+- Does this proposal involve coordinating behavior between components?
+  - (i.e. the Zarf Agent and CLI? The init package and the CLI?)
+-->
+
+## Implementation History
+
+<!--
+Major milestones in the lifecycle of a ZEP should be tracked in this section.
+Major milestones might include:
+- the `Summary` and `Motivation` sections being merged, signaling acceptance of the ZEP
+- the `Proposal` section being merged, signaling agreement on a proposed design
+- the date implementation started
+- the first Zarf release where an initial version of the ZEP was available
+- the version of Zarf where the ZEP graduated to general availability
+- when the ZEP was retired or superseded
+-->
+
+## Drawbacks
+
+<!--
+Why should this ZEP _not_ be implemented?
+-->
+
+## Alternatives
+
+<!--
+What other approaches did you consider, and why did you rule them out? These do
+not need to be as detailed as the proposal, but should include enough
+information to express the idea and why it was not acceptable.
+-->
+
+## Infrastructure Needed (Optional)
+
+<!--
+Use this section if you need things from the project. Examples include a new repo,
+cloud infrastructure for testing or GitHub details. Listing these here
+allows the process to get these resources to be started right away.
+-->
diff --git a/0026-enhanced-state-management/zep.yaml b/0026-enhanced-state-management/zep.yaml
new file mode 100644
index 0000000..1ef9c99
--- /dev/null
+++ b/0026-enhanced-state-management/zep.yaml
@@ -0,0 +1,25 @@
+schema-version: 1.0.0
+
+title: Enhanced State Management
+zep-number: 0026
+authors:
+  - "@racer159"
+status: provisional
+creation-date: 2025-04-28
+reviewers:
+  - "@zarf-dev"
+approvers:
+  - "@zarf-dev"
+
+# The target maturity stage in the current dev cycle for this ZEP.
+stage: alpha
+
+# The most recent milestone for which work toward delivery of this ZEP has been
+# done. This can be the current (upcoming) milestone, if it is being actively
+# worked on.
+latest-milestone: NA
+
+# The milestone at which this feature was, or is targeted to be, at each stage.
+milestone:
+  alpha: "v0.39"
+  stable: "v1.0"

From 3130169c531ce1359aaa3684a05af6c25fd0f52c Mon Sep 17 00:00:00 2001
From: Wayne Starr <me@racer159.com>
Date: Tue, 29 Apr 2025 12:14:02 -0600
Subject: [PATCH 2/2] refine proposal

Signed-off-by: Wayne Starr <me@racer159.com>
---
 0026-enhanced-state-management/README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/0026-enhanced-state-management/README.md b/0026-enhanced-state-management/README.md
index 417724f..a18c5aa 100644
--- a/0026-enhanced-state-management/README.md
+++ b/0026-enhanced-state-management/README.md
@@ -105,7 +105,7 @@ Currently there are a few issues that limit what you can do with Zarf due to the
 
 ## Proposal
 
-The proposed solution is to split Zarf secrets into one for each version of a package
+The proposed solution is to split Zarf secrets into one for each deployment of a package to track the changes that occur during each call of `zarf package deploy`.  This is similar to how Helm works where each release of a chart is stored in a separate secret.  Zarf would also change to label resources a package has created using the Helm post render logic. This would include both the package and the component name that created that resource.
 
 ### User Stories (Optional)