Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Group iteration on simplifying principle wording #14

Closed
wants to merge 4 commits into from
Closed

Group iteration on simplifying principle wording #14

Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
d59305d
Group iteration on simplifying principle wording
scottrigby Jul 7, 2021
e60fbe4
Updates from July 21 Principles meeting and GitHub review comments
scottrigby Jul 26, 2021
c3fa5f9
Remove redundancy from principle 3
scottrigby Jul 26, 2021
e2e424c
Bump version
scottrigby Jul 26, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 6 additions & 6 deletions PRINCIPLES.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,22 +10,22 @@ These principles were derived from modern software operations but are rooted in

## Principles

1. **The principle of declarative desired state**
1. **The system's desired state is described declaratively**
scottrigby marked this conversation as resolved.
Show resolved Hide resolved

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. **The principle of immutable desired state versions**
2. **State declarations are stored as immutable versions**
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🤏

Copy link
Member Author

@scottrigby scottrigby Jul 20, 2021 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@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.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@jlbutler

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

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@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?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@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**

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Happy to discuss: open-gitops/project#15


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

3. **The principle of continuous state reconciliation**
3. **State reconciliation is automated and continuous**
scottrigby marked this conversation as resolved.
Show resolved Hide resolved

Software agents continuously, and automatically, compare a system's _Actual State_ to its _Desired State_.
Software agents continuously, and automatically, compare a system's state to its _Desired State_.
If the actual and desired states differ for any reason, automated actions to reconcile them are initiated.
scottrigby marked this conversation as resolved.
Show resolved Hide resolved

4. **The principle of operations through declaration**
4. **Intentional change happens only through changing state declarations**
scottrigby marked this conversation as resolved.
Show resolved Hide resolved

The only mechanism through which the system is intentionally operated on is through these principles.
The only mechanism through which the system is intentionally changed is through new versions of the _Desired State_.

## Notes

Expand Down