Simplify first sentence of each principle, for easy memorization

[todaywasawesome]

Signed-off-by: Dan Garfield dan@todaywasawesome.com

The "Use" is repetitive but declarative. They can be taken as axioms this way instead of a descriptor of a longer principle beneath. I think the principle should be a short line and the additional text should clarify and expand the principle.

[williamcaban]

Since "infrastructure" can be seen in the context of physical infrastructure. I would explore different word for this.

"Use declarative pattern" or or "approach" or "model"

[todaywasawesome]

Maybe it's just "Use Declarative State" or "Define State Declaratively"

[todaywasawesome]

Updated

[todaywasawesome]

An alternative could be:

The Principles describe how your application should be run using GitOps:

• Declaratively
• Immutably
• Reconciled state continuously
• Operated solely through declaration

[williamcaban]

What about "Use immutable, versioned declaration" (to map to principle 4)

[todaywasawesome]

Maybe "Store declarations in an immutable version control system"

It's long but I think the weakness of what I have in the PR is it sounds almost like a recommendation about what kind of storage your running infra should use which doesn't make sense.

This rephrasing feels like it emphasizes the declaration.

[scottrigby]

I think the main point is to remove the redundant "The principle of" from every one-line principle summary. After having said these out loud to a number of people now, I agree that feels repetitive. Here they are now:

Current

GitOps Principles

1. The principle of declarative desired state
2. The principle of immutable desired state versions
3. The principle of continuous state reconciliation
4. The principle of operations through declaration

Option A 🤷

Doing this and nothing else would result in:

GitOps Principles

1. Declarative desired state
2. Immutable desired state versions
3. Continuous state reconciliation
4. Operations through declaration

Option B 😸

To format these as axioms, they should be statements. Something like:

GitOps Principles

1. A system's desired state must be declarative
2. Declarations must be stored as immutable versions
3. State reconciliation must be continuous
4. All operations should be through declaration

Option C 🤔

Alternatively we discussed that these could be formatted as commands. For example:

GitOps Principles

A system managed by GitOps must:

1. Declare desired state
2. Store declarations as immutable versions
3. Continuously reconcile actual state
4. Only operate on the system through declaration

Personally I like Option B above. However if it's too contentious I think option A would be a fine, simple way to remove the redundancy without further changes.

[jlbutler]

Thanks for kicking this off @todaywasawesome and for summarizing @scottrigby.

I agree with you Scott, I like Option B. I believe the principles offer most value when they are prescriptive. I guess an Option B.1 (oh no) would be to swap "must" and "should" to "is/are"

e.g.

1. A system's desired state is declarative
2. Declarations are stored as immutable versions
3. State reconciliation is continuous
4. All operations are initiated through declaration mutation

Not passionate about the wording here, but the idea might be something that makes Option B feel less "spec" and more "principle"?

[todaywasawesome]

+1 for Axioms. I want to put it on a poster. 😄

…

On Tue, Jun 22, 2021, 7:09 AM Jesse Butler ***@***.***> wrote: Thanks for kicking this off @todaywasawesome <https://github.com/todaywasawesome> and for summarizing @scottrigby <https://github.com/scottrigby>. I agree with you Scott, I like Option B. I believe the principles offer most value when they are prescriptive. I guess an Option B.1 (oh no) would be to swap "must" and "should" to "is/are" e.g. 1. A system's desired state is declarative 2. Declarations are stored as immutable versions 3. State reconciliation is continuous 4. All operations are initiated through declaration mutation Not passionate about the wording here, but the idea might be something that makes Option B feel less "spec" and more "principle"? — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#9 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AA5L5LDUR23JQIIPS5SUYY3TUCKRNANCNFSM462CTAOA> .

[williamcaban]

What about combining both: the list #9 (comment) and Option B #9 (review) (with some #9 (comment))

Into something like this:

• Declaratively: A system's desired state must be declarative
• Immutably: Declarations must be stored as immutable versions
• Continuous Reconciliation: State reconciliation must be continuous
• Declarative Operations: Operations should be through versioned mutation of the declaration

[roberthstrand]

I too like Option B, as well as the combination that @williamcaban suggests.

The way I think of it, anything that would simplify the wording in the titles of the principles is great. All of these suggestions absolutely do that.

[williamcaban]

To clarify my earlier comment #9 (comment)

It is about providing a 1-2-3 condensable version of the principles. word > one-liner > full text so it can be represented in various ways/format during communications & presentations. Putting everything together:

1. Declaratively: A system's desired state is declarative

   A system managed by GitOps must have its Desired State expressed declaratively as data in a format writable and readable by both humans and machines.

2. Immutably: Declarations are stored as immutable versions

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

3. Continuous Reconciliation: State reconciliation is continuous

   Software agents continuously, and automatically, compare a system's Actual State to its Desired State. If the actual and desired states differ for any reason, automated actions to reconcile them are initiated.

4. Declarative Operations: Operations is through versioned mutation of the declaration

   The only mechanism through which the system is intentionally operated on is through these principles.

[scottrigby]

Initial work toward #13

[scottrigby]

Superseded by #14