feat: stabilize - evaluation, providers, harden - hooks, events, context (#314)

This PR: 

* stabilizes evaluation API
* stabilizes providers
* hardens hooks, events and context
* hardens all "static context" (client-side) points

This is a pretty substantial step.
`stable` means that we have no more leeway at all in SDKs - **any
breaking changes to the parts of the SDK implementing stable APIs means
a new major version of the SDK is required, without exception**.

I've also opted to "harden" the `static context paradigm` since we have
numerous client implementations in the wild, in particular React and
Angular, but also Android. There could still be breaking changes here
but the bar is higher. I think this is how we're acting already with
regards to these APIs, in all honesty.

I did not promote the [context
propagation](https://openfeature.dev/specification/sections/evaluation-context#33-context-propagation)
sub-section, or the new tracking section - these are _relatively_ new,
though I'm open to opinions on hardening these further.

Potential blockers:

- open-feature/go-sdk#389
- #270

Signed-off-by: Todd Baert <[email protected]>

Author: toddbaert

specification/sections/01-flag-evaluation.md

@@ -6,7 +6,7 @@ toc_max_heading_level: 4
 
 # 1. Flag Evaluation API
 
-[![hardening](https://img.shields.io/static/v1?label=Status&message=hardening&color=yellow)](https://github.com/open-feature/spec/tree/main/specification#hardening)
+[![stable](https://img.shields.io/static/v1?label=Status&message=stable&color=green)](https://github.com/open-feature/spec/tree/main/specification#stable)
 
 ## Overview
 
@@ -203,7 +203,7 @@ See [evaluation context](./03-evaluation-context.md) for details.
 
 #### Condition 1.3.2
 
-[![experimental](https://img.shields.io/static/v1?label=Status&message=experimental&color=orange)](https://github.com/open-feature/spec/tree/main/specification#experimental)
+[![hardening](https://img.shields.io/static/v1?label=Status&message=hardening&color=yellow)](https://github.com/open-feature/spec/tree/main/specification#hardening)
 
 > The implementation uses the static-context paradigm.
 
@@ -285,7 +285,7 @@ FlagEvaluationDetails<MyStruct> myStructDetails = client.getObjectDetails<MyStru
 
 #### Condition 1.4.2
 
-[![experimental](https://img.shields.io/static/v1?label=Status&message=experimental&color=orange)](https://github.com/open-feature/spec/tree/main/specification#experimental)
+[![hardening](https://img.shields.io/static/v1?label=Status&message=hardening&color=yellow)](https://github.com/open-feature/spec/tree/main/specification#hardening)
 
 > The implementation uses the static-context paradigm.
 
@@ -396,7 +396,7 @@ See [hooks](./04-hooks.md) for details.
 
 ### 1.6. Shutdown
 
-[![experimental](https://img.shields.io/static/v1?label=Status&message=experimental&color=orange)](https://github.com/open-feature/spec/tree/main/specification#experimental)
+[![hardening](https://img.shields.io/static/v1?label=Status&message=hardening&color=yellow)](https://github.com/open-feature/spec/tree/main/specification#hardening)
 
 The API's `shutdown` function defines a means of graceful shutdown, calling the `shutdown` function on all providers, allowing them to flush telemetry, clean up connections, and release any relevant resources.
 It also provides a means of resetting the API object to its default state, removing all hooks, event handlers, providers, and setting a "No-op provider"; this is useful for testing purposes.
@@ -469,7 +469,7 @@ see [provider status](../types.md#provider-status)
 
 #### Condition 1.7.2
 
-[![experimental](https://img.shields.io/static/v1?label=Status&message=experimental&color=orange)](https://github.com/open-feature/spec/tree/main/specification#experimental)
+[![hardening](https://img.shields.io/static/v1?label=Status&message=hardening&color=yellow)](https://github.com/open-feature/spec/tree/main/specification#hardening)
 
 > The implementation uses the static-context paradigm.
 

specification/sections/02-providers.md

@@ -6,7 +6,7 @@ toc_max_heading_level: 4
 
 # 2. Provider
 
-[![hardening](https://img.shields.io/static/v1?label=Status&message=hardening&color=yellow)](https://github.com/open-feature/spec/tree/main/specification#hardening)
+[![stable](https://img.shields.io/static/v1?label=Status&message=stable&color=green)](https://github.com/open-feature/spec/tree/main/specification#stable)
 
 ## Overview
 
@@ -166,7 +166,7 @@ class MyProvider implements Provider {
 
 ### 2.4 Initialization
 
-[![experimental](https://img.shields.io/static/v1?label=Status&message=experimental&color=orange)](https://github.com/open-feature/spec/tree/main/specification#experimental)
+[![hardening](https://img.shields.io/static/v1?label=Status&message=hardening&color=yellow)](https://github.com/open-feature/spec/tree/main/specification#hardening)
 
 #### Requirement 2.4.1
 
@@ -209,7 +209,7 @@ see: [error codes](../types.md#error-code)
 
 ### 2.5. Shutdown
 
-[![experimental](https://img.shields.io/static/v1?label=Status&message=experimental&color=orange)](https://github.com/open-feature/spec/tree/main/specification#experimental)
+[![hardening](https://img.shields.io/static/v1?label=Status&message=hardening&color=yellow)](https://github.com/open-feature/spec/tree/main/specification#hardening)
 
 #### Requirement 2.5.1
 
@@ -245,7 +245,7 @@ see: [initialization](#24-initialization)
 
 ### 2.6. Provider context reconciliation
 
-[![experimental](https://img.shields.io/static/v1?label=Status&message=experimental&color=orange)](https://github.com/open-feature/spec/tree/main/specification#experimental)
+[![hardening](https://img.shields.io/static/v1?label=Status&message=hardening&color=yellow)](https://github.com/open-feature/spec/tree/main/specification#hardening)
 
 Static-context focused providers may need a mechanism to understand when their cache of evaluated flags must be invalidated or updated. An `on context changed` function can be defined which performs whatever operations are needed to reconcile the evaluated flags with the new context.
 

specification/sections/03-evaluation-context.md

@@ -6,7 +6,7 @@ toc_max_heading_level: 4
 
 # 3. Evaluation Context
 
-[![experimental](https://img.shields.io/static/v1?label=Status&message=experimental&color=orange)](https://github.com/open-feature/spec/tree/main/specification#experimental)
+[![hardening](https://img.shields.io/static/v1?label=Status&message=hardening&color=yellow)](https://github.com/open-feature/spec/tree/main/specification#hardening)
 
 ## Overview
 
@@ -59,7 +59,7 @@ API (global) `evaluation context` can be used to supply static data to flag eval
 
 #### Condition 3.2.2
 
-[![experimental](https://img.shields.io/static/v1?label=Status&message=experimental&color=orange)](https://github.com/open-feature/spec/tree/main/specification#experimental)
+[![hardening](https://img.shields.io/static/v1?label=Status&message=hardening&color=yellow)](https://github.com/open-feature/spec/tree/main/specification#hardening)
 
 > The implementation uses the static-context paradigm.
 
@@ -116,7 +116,7 @@ This describes the precedence of all `evaluation context` variants. Depending on
 
 #### Condition 3.2.4
 
-[![experimental](https://img.shields.io/static/v1?label=Status&message=experimental&color=orange)](https://github.com/open-feature/spec/tree/main/specification#experimental)
+[![hardening](https://img.shields.io/static/v1?label=Status&message=hardening&color=yellow)](https://github.com/open-feature/spec/tree/main/specification#hardening)
 
 > The implementation uses the static-context paradigm.
 

specification/sections/04-hooks.md

@@ -6,7 +6,7 @@ toc_max_heading_level: 4
 
 # 4. Hooks
 
-[![experimental](https://img.shields.io/static/v1?label=Status&message=experimental&color=orange)](https://github.com/open-feature/spec/tree/main/specification#experimental)
+[![hardening](https://img.shields.io/static/v1?label=Status&message=hardening&color=yellow)](https://github.com/open-feature/spec/tree/main/specification#hardening)
 
 ## Overview
 
@@ -184,7 +184,7 @@ EvaluationContext | void before(HookContext hookContext, HookHints hints);
 
 #### Condition 4.3.3
 
-[![experimental](https://img.shields.io/static/v1?label=Status&message=experimental&color=orange)](https://github.com/open-feature/spec/tree/main/specification#experimental)
+[![hardening](https://img.shields.io/static/v1?label=Status&message=hardening&color=yellow)](https://github.com/open-feature/spec/tree/main/specification#hardening)
 
 > The implementation uses the static-context paradigm.
 

specification/sections/05-events.md

@@ -6,7 +6,7 @@ toc_max_heading_level: 4
 
 # 5. Events
 
-[![experimental](https://img.shields.io/static/v1?label=Status&message=experimental&color=orange)](https://github.com/open-feature/spec/tree/main/specification#experimental)
+[![hardening](https://img.shields.io/static/v1?label=Status&message=hardening&color=yellow)](https://github.com/open-feature/spec/tree/main/specification#hardening)
 
 ## Overview
 
@@ -195,7 +195,7 @@ stateDiagram-v2
 
 #### Condition 5.3.4
 
-[![experimental](https://img.shields.io/static/v1?label=Status&message=experimental&color=orange)](https://github.com/open-feature/spec/tree/main/specification#experimental)
+[![hardening](https://img.shields.io/static/v1?label=Status&message=hardening&color=yellow)](https://github.com/open-feature/spec/tree/main/specification#hardening)
 
 > The implementation uses the static-context paradigm.