Group iteration on simplifying principle wording

[scottrigby]

• Fixes Ensure first sentence of each principle is both accurate and memorable #13

Remaining steps

• General consensus in principle meetings
• Get more reviews from principles committee and others (can we work asynchronously?) YES
  Steps to review:
  1. Preview
  2. Submit your review
• tag v1.0.0-rc.1 See Milestones for documents repo project#17 (comment)
• next step, work on issues for the next milestones planned before the full release

Context

This was worked on during GitOps Working Group Principles Committee meetings over the past few weeks, and asynchronously in Slack/GitHub.

Participants

Zoom:

Co-authored-by: Jesse Butler <[email protected]>
Co-authored-by: William Caban <[email protected]>
Co-authored-by: Dan Garfield <[email protected]>
Co-authored-by: Moshe Immerman <[email protected]>
Co-authored-by: Christian Hernandez <[email protected]>
Co-authored-by: Leonardo Murillo <[email protected]>
Co-authored-by: Scott Rigby <[email protected]>
Co-authored-by: Chris Sanders <[email protected]>
Co-authored-by: Roberth Strand <[email protected]>
Co-authored-by: Daniel Warner <[email protected]>

GitHub:

Co-authored-by: Florian Heubeck <[email protected]>
Co-authored-by: Lloyd Chang <[email protected]>

[scottrigby]

Seeing how this looks on the website preview, it still feels a bit clunky.

The paragraph for each principle already is very succinct and precise. We just need a short, memorable reference for each of those, so people can easily remember them in order.

What about this below? Each builds on a relevant piece of the previous statement, so does not need to repeat anything. Minimal changes from the last working session with a goal of keeping these as short and clear (5 words or less). WDYT?

1. Desired System State is Declarative
2. Declarations are Version Controlled
3. State Reconciliation is Continuous
4. System Changes Only Through Versioning

Or something short and sweet to this effect?

Click for website previews

v0.1.0

Just remove "the principle of" from v0.1.0

This proposed change

[scottrigby]

Suggested change

	2. **State declarations are stored as immutable versions**
	2. **Declarations are Version Controlled**

[lloydchang]

Suggested change

	2. **State declarations are stored as immutable versions**
	2. **Declarations are Versioned**

[lloydchang]

🤏

[scottrigby]

@lloydchang Thanks!

Re #14 (review), I do personally agree the shorter and more memorable/catchy we can make these principle headers the better 🤏 🙂

I wonder though if "versioned" here is enough, whereas "version controlled" seems to me to check all the boxes of this principle. But do you not feel these have different meanings?

Desired State is stored in a way that supports versioning, immutability of versions, and retains a complete version history.

[scottrigby]

@jlbutler

Suggested change

	2. **State declarations are stored as immutable versions**
	2. **Declarations are versioned and Immutable**

[scottrigby]

@jlbutler Updated the PR.

@heubeck thanks for this suggestion! I haven't added this to the branch yet because I think we'd need more discussion on that first. but I added you as co-author to this commit as well since you're collaborating with us here on GitHub. I'd like us to get this PR merged soon, but we can continue iterating. Are you free to join the next principles meeting on Wednesday?

[heubeck]

@scottrigby Thank you, I'll try to participate.

[heubeck]

Regarding my audit-proof suggestion: Technically it means the same as the phrases with immutable and versions, but the statement is much stronger.
Industries with deployment revision logging ("audit") demands may appreciate a less technical terminology.

[scottrigby]

@heubeck this is really interesting. Given how close this PR is to being merged for v0.2.0, and how important it is to simplify the headers ASAP, let's discuss this idea for a next iteration 🙏

Would you be willing to move this idea to a discussion in the OpenGitOps project repo? That way there is a place for async discussion on this before and after the next meeting (tomorrow). The discussion could recommend this change from the current PR, and see how that sits with the principles committee and community?

- 2. **Declarations Are Versioned and Immutable**
+ 2. **Declarations Are Versioned and Audit-Proof**

[heubeck]

Happy to discuss: open-gitops/project#15

[lloydchang]

👍 for 1, 3
🤏 Shorten 2 from Version Controlled to Versioned; added 🤏 suggestion
👎 for 4 because Changes aren't limited to System; added 🤏 suggestion
Thanks @scottrigby

[lloydchang]

Suggested change

	2. **State declarations are stored as immutable versions**
	2. **Declarations are Versioned**

[lloydchang]

Suggested change

	2. **Declarations Are Versioned and Immutable**
	2. **Declarations are Versioned and Immutable**

Typographic Suggestion:
Are -> are
to align with
https://user-images.githubusercontent.com/407675/126000898-eb81abd1-a947-40e4-b313-107fd45b7ad7.png
Thanks @scottrigby

[scottrigby]

@lloydchang Yeah I wasn't sure about which title case style we want to adopt. I would recommend not getting too caught up in this question, and that we follow some existing style guide. For now I just chose AP style AP style Title Case so I didn't have to think about it.

If interested though, this is a fun tool to see how the different standards look https://titlecaseconverter.com/

Note "Is" is capitalized in every style. "Through" varies across the standards.

[jlbutler]

Given this PR increments a pre-GA version I'm going to say LGTM. We can iterate more, I'd rather see that happen in subsequent PRs at this point as this captures common inputs from a few meetings.

Thanks @scottrigby for herding the cats on this! 🚀

[christianh814]

I'm going to +1 @jlbutler . I have some thoughts on how they are now (specifically with principal 4). But this is a good iteration. I say LGTM

[scottrigby]

I'm not the sole author of this, just the wrangler. Given that, I also want to give my +1 to merging as-is for v0.2.0

[moshloop]

I am +1 for merging and iterating, not so sure that we should tag it until we at a minimum solve consistency and grammatical issues.

[williamcaban]

What about 4. Actualizations to Declarations are versioned

[williamcaban]

Note: Not sure if these are interchangeable in this context Actualizations to Declarations... vs Updates to Declarations... vs Changes to Declarations...

[scottrigby]

🤔

[scottrigby]

To address grammar:

Suggested change

	4. **Intentional Changes Only Through Versioning**
	4. **Intentional Changes are Only Through Versioning**

[scottrigby]

🤔

[scottrigby]

The WG is struggling with making Principle 4 both precise and memorable. I think this is because the group has liked the idea of being able to essentially say "a GitOps managed system should be operated only through these principles" inside the principles themselves, with no further introduction. However that is not really a principle in itself. This was exactly what @bgrant0607 said when Dan asked for feedback on v0.1.0.

After trying so many options to make it fit, I'm very tempted to agree we may just need to simply make that clear when introducing the principles, and not try to squeeze it in as a principle itself.

[scottrigby]

To be clear, these principle titles are very similar to the original ones proposed by Weaveworks in 2017. The main difference being the initial change proposed by @bricef, which combined the original 3 & 4 into our current # 3:

3. State Reconciliation Is Continuous
   Software agents continuously, and automatically, compare a system's state to its Desired State. If these states differ for any reason, automated actions to reconcile them are initiated.

The only significant difference is we don't mention alerting on divergence. So far in WG discussions people have felt that is an important implementation detail, but not needed as a foundational principle. I'm, personally rethinking that now 🤔

As this PR stands, how does everyone feel about removing the additional principle 4, and/or bringing back the feedback loop concept as part of # 4?

[jlbutler]

@scottrigby I think you're correct in the collapsing of 3 & 4 being the main cause of "number four is hard". This quickly became the "and we mean it" principle because we're covering the high order bits of 4 principles now in 3.

I would be happy to explore what 3 principles looks like in review. I wonder if it might make sense to drop the tag increment from this PR and merge everything so far, then in a subsequent issue propose and discuss a 3-principle format?

[todaywasawesome]

I suggest leaving principle 4 at the moment and cutting a 0.2.0 release. What we have in this PR is an improvement, lets take that win and move forward. @scottrigby @jlbutler

[drwarner]

At this point my inclination would be merge this PR as well. I think the proposal to drop principle 4 should be discussed for 0.3.0 though.

[scottrigby]

closing in favor of #21