RC 1 draft

[scottrigby]

Call to action

Please give your feedback here. Note we agreed to move to an RC process in order to make more rapid incremental progress toward a full release, while allowing for group feedback between RC releases.

Milestone dates reminder: tag RC 1 by this Friday, full 1.0.0 release before KubeCon.

• Fixes: Ensure first sentence of each principle is both accurate and memorable #13
• Fixes: Reconcile all community feedback and participation related to the GitOps Principles #18
• Fixes: Principles version in markdown may not match current revision viewed #20

Does not yet claim to fix this issue, but please keep this in mind during review. Accessibility is an ongoing process:

• Ensure documents language is accessible and inclusive #73

Context

⚠️ This RC 1 draft may feel a little like deja vu. It is closer to the initial principles as they have been all this time in the WG README.

Why? Over the past 6 months of meetings, we started by merging several of the initial principles. This was in part my doing, but it was an understandable direction at the time. As we began to update them from there with more precise wording as a group, the first few went smoothly. However, because each principle builds upon the previous ones, as we got closer to the end it became increasingly complex to figure out which pieces of which ideas should be in each, not quite being able to get all the way through them due to detailed debates each week. Important points were made by all.

However the diminishing returns in later meetings is what prompted the decision to accelerate revising the principles through a RC/feedback process, where each RC attempts to integrate the very valuable points that were made by the group over the past months in a coherent way.

In retrospect, a hypothesis is that merging several of the initial principles early on exacerbated the increasing complexity in bringing precise and consistent language to the later steps. This RC 1 draft attempts to solve that by rolling back to the initial version, and trying to make the fewest changes necessary to reconcile points and feedback from the principles committee that seem to have stood the test of time. So while this draft is very similar to the initial principles, there are some important changes that try to reconcile them with the points we made as a group. I hope you can see this in the draft by comparing the two (have a look at the initial commit for an easily viewable comparison of only those changes: f15f4ee).

Items left out of this PR

Existing principle 5

We're not including this in the draft as of now because it's not clear how to explain it's necessity for GitOps. Why exactly was this principle here initially? Control theory language is valuable, but is it necessary here?

• Is it to say the software agents must take into account feedback/output from the observed actual state in deciding how or if to reconcile? If so, how is this different than what we already say in principle 4?
• Is it so say the software agents must take into account feedback/output from any previous reconciliation attempts (for example number of retries before stopping and notifying)?
• Since we are unclear on it's value add to the other 4 principles, we've left it out of the RC1 draft for now.
• Is this principle important for notifications?

5. Operated in a closed loop
   Software agents observe desired state and meta-state to take actions based on policy when the desired state cannot be reached. This may include things like notifications, rollbacks, etc.

Potential new principle 6

We had discussed splitting this note from principle 4 into its own principle, to emphasize this as a critical point for GitOps. We are unclear whether we feel as a group this is already clear from the current wording of principle 4, or is this needs an additional explicit kick.

6. The Source of Truth
   Declared desired state will always take precedence over any other source of configuration.

To-do

• Bring over co-authorship participation notes from Group iteration on simplifying principle wording #14 into a commit here, or when squashing this PR's commits
• Also add co-authorship credits to additional people who participate in this PR

[RedbackThomson]

Looks good to me, now!

[williamcaban]

comments inline

The rest looks good to me

[williamcaban]

The attempt to apply might not communicate the imperative need for the software agent to actually work towards the reconciliation.

What about:
...observe actual system state and on drift reconcile towards the desired state.

[scottrigby]

I'd like to hear what you think about this section of the PR description above: "items left out of this PR" > "existing principal 5" > "5. Operated in a closed loop"? This is the principle that addresses a feedback loop based on configurations in the desired state and the output of attempts to apply to the actual state.

[todaywasawesome]

After thinking about it I think I'm more in favor of attempt to apply which can mean a lot. We could potentially add more to the glossary.

[scottrigby]

Sounds like this is not a blocker for RC 1. @williamcaban let's continue to discuss this during the process when we send out RC 1 for feedback for folks. Most likely that will be in the form of a GitHub Discussion ❤️

[williamcaban]

My concern with attempt to apply is that it could open the interpretation that a series of remediations were attempted (lets say remediation A & B) and even if not successful it can attempt additional ones (eg. remediations C & D) which might lead to a situation of unrecoverable drift state (which brings us back to the snowflakes configurations results and desired state vs running state open to divergence)

How can we phrase it in a way that an attempt is not enough, but that it must continue trying remediate?

[williamcaban]

WRT leaving principle 5, agree as it might be covered by principle 3. At least I have not found any extremely compelling example not covers by the other principles. The more concise the better.

[moshloop]

LGTM

[todaywasawesome]

Removing "Break Glass" can wait until the RC feedback stage if you're more comfortable. I made some small grammar fixes and added hyperlinks for terms in the gloassary. I think we're good to move forward.

[todaywasawesome]

After thinking about it I think I'm more in favor of attempt to apply which can mean a lot. We could potentially add more to the glossary.

[todaywasawesome]

Suggested change

	- ## Break Glass
	The temporary suspension of GitOps principles, often accomplished by pausing automated _Reconciliation_.
	While these principles apply to typical operations, it may at times be necessary to temporarily pause reconciliation, for example during incident management activities.
	In these cases, other modes of operations should be considered (e.g. manual intervention), followed by any necessary updates to the desired state declarations, and finally resuming reconciliation of the system with the updated declarations.
	Pragmatic exceptions to these guiding principles are expected from time to time during the journey toward a system being fully managed by GitOps.

I would remove this because it is not the language used in the principles. The glossary should only include terms in the principles and not act as a place for exploring other ideas like when GitOps should and shouldn't apply.

[scottrigby]

Agree with what you said here #21 (review):

Removing "Break Glass" can wait until the RC feedback stage if you're more comfortable... I think we're good to move forward.

Making minor grammar, formatting and link fixes is ok even after others have reviewed this PR, but I am more comfortable leaving this as-is for now and discussing your point as part of the feedback for RC 1, given that the goal of that is to get wider feedback through an RC/feedback process from the group (including us) and wider community. Otherwise I think we'd need to wait for re-review by everyone on this PR. Instead let's meet the milestone to release RC 1 today.

[csand-msft]

Approve RC1

[murillodigital]

LGTM! 🎉🎉🎉

[csantanapr]

LGTM

[scottrigby]

Thanks everyone! Please see the squashed commit message for detailed attribution: 11b362b

RC 1 tag forthcoming

[scottrigby]

Tag created! 🎉 https://github.com/open-gitops/documents/releases/tag/v1.0.0-rc.1

Please broadcast widely for feedback from the wider GitOps community 📣 🦄 ✨

[lloydchang]

LGTM