From b338cb54a9d672e1e5d61e6842251fb9086a17cb Mon Sep 17 00:00:00 2001 From: Nikita Bishonen Date: Sun, 13 Nov 2022 21:21:44 +0400 Subject: [PATCH 1/2] Fix usage of wrong type instead of resolution details Evaluation details and flag evaluation names usages for resolution details type were fixed. Signed-off-by: Nikita Bishonen --- specification/sections/02-providers.md | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/specification/sections/02-providers.md b/specification/sections/02-providers.md index be8ea16d..a6d4abdb 100644 --- a/specification/sections/02-providers.md +++ b/specification/sections/02-providers.md @@ -32,14 +32,14 @@ provider.getMetadata().getName(); // "my-custom-provider" ##### Requirement 2.2.1 -> The `feature provider` interface **MUST** define methods to resolve flag values, with parameters `flag key` (string, required), `default value` (boolean | number | string | structure, required) and `evaluation context` (optional), which returns a `flag resolution` structure. +> The `feature provider` interface **MUST** define methods to resolve flag values, with parameters `flag key` (string, required), `default value` (boolean | number | string | structure, required) and `evaluation context` (optional), which returns a `resolution details` structure. ```typescript // example flag resolution function resolveBooleanValue(flagKey, defaultValue, context); ``` -see: [flag resolution structure](../types.md#flag-resolution), [flag value resolution](../glossary.md#flag-value-resolution) +see: [flag resolution structure](../types.md#resolution-details), [flag value resolution](../glossary.md#flag-value-resolution) ##### Condition 2.2.2 @@ -65,11 +65,11 @@ ResolutionDetails resolveStructureValue(string flagKey, JsonObject defaultValue, ##### Requirement 2.2.3 -> In cases of normal execution, the `provider` **MUST** populate the `flag resolution` structure's `value` field with the resolved flag value. +> In cases of normal execution, the `provider` **MUST** populate the `resolution details` structure's `value` field with the resolved flag value. ##### Requirement 2.2.4 -> In cases of normal execution, the `provider` **SHOULD** populate the `flag resolution` structure's `variant` field with a string identifier corresponding to the returned flag value. +> In cases of normal execution, the `provider` **SHOULD** populate the `resolution details` structure's `variant` field with a string identifier corresponding to the returned flag value. For example, the flag value might be `3.14159265359`, and the variant field's value might be `"pi"`. @@ -77,19 +77,19 @@ The value of the variant field might only be meaningful in the context of the fl ##### Requirement 2.2.5 -> The `provider` **SHOULD** populate the `flag resolution` structure's `reason` field with `"DEFAULT",` `"TARGETING_MATCH"`, `"SPLIT"`, `"DISABLED"`, `"UNKNOWN"`, `"ERROR"` or some other string indicating the semantic reason for the returned flag value. +> The `provider` **SHOULD** populate the `resolution details` structure's `reason` field with `"DEFAULT",` `"TARGETING_MATCH"`, `"SPLIT"`, `"DISABLED"`, `"UNKNOWN"`, `"ERROR"` or some other string indicating the semantic reason for the returned flag value. -As indicated in the definition of the [`flag resolution`](../types.md#resolution-details) structure, the `reason` should be a string. This allows providers to reflect accurately why a flag was resolved to a particular value. +As indicated in the definition of the [`resolution details`](../types.md#resolution-details) structure, the `reason` should be a string. This allows providers to reflect accurately why a flag was resolved to a particular value. ##### Requirement 2.2.6 -> In cases of normal execution, the `provider` **MUST NOT** populate the `flag resolution` structure's `error code` field, or otherwise must populate it with a null or falsy value. +> In cases of normal execution, the `provider` **MUST NOT** populate the `resolution details` structure's `error code` field, or otherwise must populate it with a null or falsy value. ##### Requirement 2.2.7 > In cases of abnormal execution, the `provider` **MUST** indicate an error using the idioms of the implementation language, with an associated `error code` and optional associated `error message`. -The provider might throw an exception, return an error, or populate the `error code` object on the returned `flag resolution` structure to indicate a problem during flag value resolution. +The provider might throw an exception, return an error, or populate the `error code` object on the returned `resolution details` structure to indicate a problem during flag value resolution. See [error code](../types.md#error-code) for details. @@ -104,7 +104,7 @@ throw new ProviderError(ErrorCode.INVALID_CONTEXT, "The 'foo' attribute must be ###### Conditional Requirement 2.2.8.1 -> The `flag resolution` structure **SHOULD** accept a generic argument (or use an equivalent language feature) which indicates the type of the wrapped `value` field. +> The `resolution details` structure **SHOULD** accept a generic argument (or use an equivalent language feature) which indicates the type of the wrapped `value` field. ```typescript // example boolean flag value resolution with generic argument @@ -145,8 +145,8 @@ class MyProvider implements Provider { #### Requirement 2.3.2 -> In cases of normal execution, the `provider` **MUST NOT** populate the `flag resolution` structure's `error message` field, or otherwise must populate it with a null or falsy value. +> In cases of normal execution, the `provider` **MUST NOT** populate the `resolution details` structure's `error message` field, or otherwise must populate it with a null or falsy value. #### Requirement 2.3.3 -> In cases of abnormal execution, the `evaluation details` structure's `error message` field **MAY** contain a string containing additional detail about the nature of the error. +> In cases of abnormal execution, the `resolution details` structure's `error message` field **MAY** contain a string containing additional detail about the nature of the error. From 9c31ccd7c842ffaa2bd847343dff61c624c86217 Mon Sep 17 00:00:00 2001 From: Todd Baert Date: Fri, 2 Dec 2022 09:53:08 -0500 Subject: [PATCH 2/2] fixup: update json Signed-off-by: Todd Baert --- specification.json | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/specification.json b/specification.json index c5286718..cd6e4cd7 100644 --- a/specification.json +++ b/specification.json @@ -194,7 +194,7 @@ { "id": "Requirement 2.2.1", "machine_id": "requirement_2_2_1", - "content": "The `feature provider` interface MUST define methods to resolve flag values, with parameters `flag key` (string, required), `default value` (boolean | number | string | structure, required) and `evaluation context` (optional), which returns a `flag resolution` structure.", + "content": "The `feature provider` interface MUST define methods to resolve flag values, with parameters `flag key` (string, required), `default value` (boolean | number | string | structure, required) and `evaluation context` (optional), which returns a `resolution details` structure.", "RFC 2119 keyword": "MUST", "children": [] }, @@ -216,28 +216,28 @@ { "id": "Requirement 2.2.3", "machine_id": "requirement_2_2_3", - "content": "In cases of normal execution, the `provider` MUST populate the `flag resolution` structure's `value` field with the resolved flag value.", + "content": "In cases of normal execution, the `provider` MUST populate the `resolution details` structure's `value` field with the resolved flag value.", "RFC 2119 keyword": "MUST", "children": [] }, { "id": "Requirement 2.2.4", "machine_id": "requirement_2_2_4", - "content": "In cases of normal execution, the `provider` SHOULD populate the `flag resolution` structure's `variant` field with a string identifier corresponding to the returned flag value.", + "content": "In cases of normal execution, the `provider` SHOULD populate the `resolution details` structure's `variant` field with a string identifier corresponding to the returned flag value.", "RFC 2119 keyword": "SHOULD", "children": [] }, { "id": "Requirement 2.2.5", "machine_id": "requirement_2_2_5", - "content": "The `provider` SHOULD populate the `flag resolution` structure's `reason` field with `\"DEFAULT\",` `\"TARGETING_MATCH\"`, `\"SPLIT\"`, `\"DISABLED\"`, `\"UNKNOWN\"`, `\"ERROR\"` or some other string indicating the semantic reason for the returned flag value.", + "content": "The `provider` SHOULD populate the `resolution details` structure's `reason` field with `\"DEFAULT\",` `\"TARGETING_MATCH\"`, `\"SPLIT\"`, `\"DISABLED\"`, `\"UNKNOWN\"`, `\"ERROR\"` or some other string indicating the semantic reason for the returned flag value.", "RFC 2119 keyword": "SHOULD", "children": [] }, { "id": "Requirement 2.2.6", "machine_id": "requirement_2_2_6", - "content": "In cases of normal execution, the `provider` MUST NOT populate the `flag resolution` structure's `error code` field, or otherwise must populate it with a null or falsy value.", + "content": "In cases of normal execution, the `provider` MUST NOT populate the `resolution details` structure's `error code` field, or otherwise must populate it with a null or falsy value.", "RFC 2119 keyword": "MUST NOT", "children": [] }, @@ -257,7 +257,7 @@ { "id": "Conditional Requirement 2.2.8.1", "machine_id": "conditional_requirement_2_2_8_1", - "content": "The `flag resolution` structure SHOULD accept a generic argument (or use an equivalent language feature) which indicates the type of the wrapped `value` field.", + "content": "The `resolution details` structure SHOULD accept a generic argument (or use an equivalent language feature) which indicates the type of the wrapped `value` field.", "RFC 2119 keyword": "SHOULD", "children": [] } @@ -273,14 +273,14 @@ { "id": "Requirement 2.3.2", "machine_id": "requirement_2_3_2", - "content": "In cases of normal execution, the `provider` MUST NOT populate the `flag resolution` structure's `error message` field, or otherwise must populate it with a null or falsy value.", + "content": "In cases of normal execution, the `provider` MUST NOT populate the `resolution details` structure's `error message` field, or otherwise must populate it with a null or falsy value.", "RFC 2119 keyword": "MUST NOT", "children": [] }, { "id": "Requirement 2.3.3", "machine_id": "requirement_2_3_3", - "content": "In cases of abnormal execution, the `evaluation details` structure's `error message` field MAY contain a string containing additional detail about the nature of the error.", + "content": "In cases of abnormal execution, the `resolution details` structure's `error message` field MAY contain a string containing additional detail about the nature of the error.", "RFC 2119 keyword": "MAY", "children": [] },