search

open-gitops / documents

📑 Lasting documents from the OpenGitOps project which are versioned and released together (including the GitOps Principles and Glossary)
https://opengitops.dev/
Other
420 stars 47 forks source link

Simplify first sentence of each principle, for easy memorization #9

Closed todaywasawesome closed 3 years ago

todaywasawesome commented 3 years ago

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.

todaywasawesome commented 3 years ago

An alternative could be:

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

jlbutler commented 3 years ago

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 commented 3 years ago

+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 https://github.com/open-gitops/documents/pull/9#issuecomment-866017131, or unsubscribe https://github.com/notifications/unsubscribe-auth/AA5L5LDUR23JQIIPS5SUYY3TUCKRNANCNFSM462CTAOA .

williamcaban commented 3 years ago

What about combining both: the list https://github.com/open-gitops/documents/pull/9#issuecomment-862655357 and Option B https://github.com/open-gitops/documents/pull/9#pullrequestreview-687563858 (with some https://github.com/open-gitops/documents/pull/9#issuecomment-866017131)

Into something like this:

roberthstrand commented 3 years ago

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 commented 3 years ago

To clarify my earlier comment https://github.com/open-gitops/documents/pull/9#issuecomment-866419434

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 commented 3 years ago

Initial work toward #13

scottrigby commented 3 years ago

Superseded by #14