Merge pull request #15 from open-gitops/move-notes

Address notes on the principles and remove the notes section

Author: scottrigby

PRINCIPLES.md

@@ -27,31 +27,37 @@ These principles were derived from modern software operations but are rooted in
 
     The only mechanism through which the system is intentionally operated on is through these principles.
 
-## Notes
-
-### Principle 3 Notes
-
-- These differences could be due to the actual state drifting from the desired state, or the desired state changing intentionally.
-- The source of drift doesn't matter. Contrary to CIops, _any_ drift will trigger a reconciliation
-
-### Principle 4 Notes
+## Glossary
 
-- We talk here about "regular operations." In an emergency, other modes of operations, e.g. manual intervention, should be considered - followed by a reconciliation of the "tainted" system with the declared state. → resolve the conflict between "GitOps principle" and "I need to deal with problems that GitOps doesn't cover"
+- ### Break Glass
 
-## Glossary
+    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.
 
 - ### Continuous
 
-    By "continuous" we adopt the industry standard term to mean reconciliation continues to happen, not that it must be instantaneous.
+    By "continuous" we adopt the industry standard to mean that _Reconciliation_ continues to happen, not that it must be instantaneous.
 
 - ### Declarative Description
 
-    Describing the desired state or behavior of a system without specifying how that state will be achieved, thereby separating between configuration - the desired state - and implementation - the commands, API calls, scripts ... that actually achieve the desired state described in the declarative description.
+    Describing the desired state or behavior of a system without specifying how that state will be achieved, thereby separating configuration (the desired state) from the implementation (commands, API calls, scripts etc.) that actually achieves the desired state described in the declarative description.
 
 - ### Desired State
 
     The aggregate of all configuration data for a system form its _Desired State_ which is defined as data sufficient to recreate the system so that instances of the system are behaviourally indistinguishable.
 
+- ### Drift
+
+    When a system's _Actual State_ changes for any reason other than its versioned _Desired State_ declarations having changed, we say that the system has drifted from its _Desired State_.
+
+- ### Reconciliation
+
+    The process of ensuring that the _Actual State_ of a sytem matches its versioned _Desired State_ declarations.
+    Contrary to CIops, any divergence between the two will trigger reconciliation, regardless of where changes occured.
+    Divergence could be due to the actual state unintentionally _Drifting_ from the desired state declarations, or a new desired state declaration version having been changed intentionally.
+
 - ### Software System
 
     One or more Runtime environments consisting of resources under management.
@@ -60,6 +66,9 @@ These principles were derived from modern software operations but are rooted in
     One or more Administrators who are responsible for operating the runtime environments ie. installing, starting, stopping and updating software, code, configuration, etc.
     A set of policies controlling access and management of repositories, deployments, runtimes.
 
-- #### State Store
+- ### State Store
 
-    A system for storing versioned, immutable Desired States that provides access control and auditing on the changes to the Desired State. Git may be configured as a State Store, but [special precautions must be taken](recipes/SETTING_UP_GIT.md).
+    A system for storing immutable versions of _Desired State_ declarations.
+    This state store should provide access control and auditing on the changes to the Desired State.
+    Git is the canonical example used as this State Store, and where GitOps derived its name, but but any other system that meets this criteria may be used.
+    In all cases these must be properly configured, and special precautions must be taken to comply with requirements set out in the GitOps Principles.