Codegen feature-branch: make stability and deprecation independent pr…

…operties (#244) (#280)

semantic-conventions/CHANGELOG.md

@@ -8,6 +8,8 @@ Please update the changelog as part of any significant pull request.
   [BREAKING] The `--file-per-group <pattern>` that used to create multiple directories (like `output/<pattern>/file`) now generates
   multiple files (`output/<pattern>file`) instead.
   ([#243](https://github.com/open-telemetry/build-tools/pull/243))
+- BREAKING: Make stability and deprecation independent properties.
+  ([#244](https://github.com/open-telemetry/build-tools/pull/244))
 
 ## v0.23.0
 

semantic-conventions/src/opentelemetry/semconv/model/semantic_attribute.py

@@ -41,7 +41,6 @@ class RequirementLevel(Enum):
 class StabilityLevel(Enum):
     STABLE = 1
     EXPERIMENTAL = 2
-    DEPRECATED = 3
 
 
 @dataclass
@@ -83,9 +82,7 @@ def is_enum(self):
         return isinstance(self.attr_type, EnumAttributeType)
 
     @staticmethod
-    def parse(
-        prefix, semconv_stability, yaml_attributes
-    ) -> "Dict[str, SemanticAttribute]":
+    def parse(prefix, yaml_attributes) -> "Dict[str, SemanticAttribute]":
         """This method parses the yaml representation for semantic attributes
         creating the respective SemanticAttribute objects.
         """
@@ -180,21 +177,13 @@ def parse(
                 raise ValidationError.from_yaml_pos(position, msg)
 
             tag = attribute.get("tag", "").strip()
-            stability, deprecated = SemanticAttribute.parse_stability_deprecated(
-                attribute.get("stability"), attribute.get("deprecated"), position_data
+            stability = SemanticAttribute.parse_stability(
+                attribute.get("stability"), position_data
             )
-            if (
-                semconv_stability == StabilityLevel.DEPRECATED
-                and stability is not StabilityLevel.DEPRECATED
-            ):
-                position = (
-                    position_data["stability"]
-                    if "stability" in position_data
-                    else position_data["deprecated"]
-                )
-                msg = f"Semantic convention stability set to deprecated but attribute '{attr_id}' is {stability}"
-                raise ValidationError.from_yaml_pos(position, msg)
-            stability = stability or semconv_stability or StabilityLevel.EXPERIMENTAL
+            deprecated = SemanticAttribute.parse_deprecated(
+                attribute.get("deprecated"), position_data
+            )
+
             sampling_relevant = (
                 AttributeType.to_bool("sampling_relevant", attribute)
                 if attribute.get("sampling_relevant")
@@ -297,43 +286,31 @@ def parse_attribute(attribute):
         return attr_type, str(brief), examples
 
     @staticmethod
-    def parse_stability_deprecated(stability, deprecated, position_data):
-        if deprecated is not None and stability is None:
-            stability = "deprecated"
-        if deprecated is not None:
-            if stability is not None and stability != "deprecated":
-                position = position_data["deprecated"]
-                msg = f"There is a deprecation message but the stability is set to '{stability}'"
-                raise ValidationError.from_yaml_pos(position, msg)
-            if AttributeType.get_type(deprecated) != "string" or deprecated == "":
-                position = position_data["deprecated"]
-                msg = (
-                    "Deprecated field expects a string that specifies why the attribute is deprecated and/or what"
-                    " to use instead! "
-                )
-                raise ValidationError.from_yaml_pos(position, msg)
-            deprecated = deprecated.strip()
-        if stability is not None:
-            stability = SemanticAttribute.check_stability(
-                stability,
-                position_data["stability"]
-                if "stability" in position_data
-                else position_data["deprecated"],
-            )
-        return stability, deprecated
+    def parse_stability(stability, position_data):
+        if stability is None:
+            return StabilityLevel.EXPERIMENTAL
 
-    @staticmethod
-    def check_stability(stability_value, position):
         stability_value_map = {
-            "deprecated": StabilityLevel.DEPRECATED,
             "experimental": StabilityLevel.EXPERIMENTAL,
             "stable": StabilityLevel.STABLE,
         }
-        val = stability_value_map.get(stability_value)
+        val = stability_value_map.get(stability)
         if val is not None:
             return val
-        msg = f"Value '{stability_value}' is not allowed as a stability marker"
-        raise ValidationError.from_yaml_pos(position, msg)
+        msg = f"Value '{stability}' is not allowed as a stability marker"
+        raise ValidationError.from_yaml_pos(position_data["stability"], msg)
+
+    @staticmethod
+    def parse_deprecated(deprecated, position_data):
+        if deprecated is not None:
+            if AttributeType.get_type(deprecated) != "string" or deprecated == "":
+                msg = (
+                    "Deprecated field expects a string that specifies why the attribute is deprecated and/or what"
+                    " to use instead! "
+                )
+                raise ValidationError.from_yaml_pos(position_data["deprecated"], msg)
+            return deprecated.strip()
+        return None
 
     def equivalent_to(self, other: "SemanticAttribute"):
         if self.attr_id is not None:

semantic-conventions/src/opentelemetry/semconv/model/semantic_convention.py

@@ -140,17 +140,18 @@ def __init__(self, group):
         self.semconv_id = self.id
         self.note = group.get("note", "").strip()
         self.prefix = group.get("prefix", "").strip()
-        stability = group.get("stability")
-        deprecated = group.get("deprecated")
         position_data = group.lc.data
-        self.stability, self.deprecated = SemanticAttribute.parse_stability_deprecated(
-            stability, deprecated, position_data
+        self.stability = SemanticAttribute.parse_stability(
+            group.get("stability"), position_data
+        )
+        self.deprecated = SemanticAttribute.parse_deprecated(
+            group.get("deprecated"), position_data
         )
         self.extends = group.get("extends", "").strip()
         self.events = group.get("events", ())
         self.constraints = parse_constraints(group.get("constraints", ()))
         self.attrs_by_name = SemanticAttribute.parse(
-            self.prefix, self.stability, group.get("attributes")
+            self.prefix, group.get("attributes")
         )
 
     def contains_attribute(self, attr: "SemanticAttribute"):

semantic-conventions/src/opentelemetry/semconv/templating/code.py

@@ -190,7 +190,7 @@ def is_stable(obj: typing.Union[SemanticAttribute, BaseSemanticConvention]) -> b
 
 
 def is_deprecated(obj: typing.Union[SemanticAttribute, BaseSemanticConvention]) -> bool:
-    return obj.stability == StabilityLevel.DEPRECATED
+    return obj.deprecated is not None
 
 
 def is_experimental(

semantic-conventions/src/opentelemetry/semconv/templating/markdown/__init__.py

@@ -119,19 +119,19 @@ def to_markdown_attr(
             if "deprecated" in attribute.deprecated.lower():
                 description = f"**{attribute.deprecated}**<br>"
             else:
-                deprecated_msg = self.options.md_snippet_by_stability_level[
-                    StabilityLevel.DEPRECATED
-                ].format(attribute.deprecated)
+                deprecated_msg = self.options.deprecated_md_snippet().format(
+                    attribute.deprecated
+                )
                 description = f"{deprecated_msg}<br>"
         elif (
             attribute.stability == StabilityLevel.STABLE and self.options.enable_stable
         ):
-            description = f"{self.options.md_snippet_by_stability_level[StabilityLevel.STABLE]}<br>"
+            description = f"{self.options.stable_md_snippet()}<br>"
         elif (
             attribute.stability == StabilityLevel.EXPERIMENTAL
             and self.options.enable_experimental
         ):
-            description = f"{self.options.md_snippet_by_stability_level[StabilityLevel.EXPERIMENTAL]}<br>"
+            description = f"{self.options.experimental_md_snippet()}<br>"
         description += attribute.brief
         if attribute.note:
             self.render_ctx.add_note(attribute.note)

semantic-conventions/src/opentelemetry/semconv/templating/markdown/options.py

@@ -15,24 +15,9 @@
 from dataclasses import dataclass, field
 from typing import List
 
-from opentelemetry.semconv.model.semantic_attribute import StabilityLevel
-
 
 @dataclass()
 class MarkdownOptions:
-
-    _badge_map = {
-        StabilityLevel.DEPRECATED: "![Deprecated](https://img.shields.io/badge/-deprecated-red)",
-        StabilityLevel.EXPERIMENTAL: "![Experimental](https://img.shields.io/badge/-experimental-blue)",
-        StabilityLevel.STABLE: "![Stable](https://img.shields.io/badge/-stable-lightgreen)",
-    }
-
-    _label_map = {
-        StabilityLevel.DEPRECATED: "**Deprecated: {}**",
-        StabilityLevel.EXPERIMENTAL: "**Experimental**",
-        StabilityLevel.STABLE: "**Stable**",
-    }
-
     check_only: bool = False
     enable_stable: bool = False
     enable_experimental: bool = False
@@ -41,8 +26,17 @@ class MarkdownOptions:
     break_count: int = 50
     exclude_files: List[str] = field(default_factory=list)
 
-    @property
-    def md_snippet_by_stability_level(self):
+    def stable_md_snippet(self):
+        if self.use_badge:
+            return "![Stable](https://img.shields.io/badge/-stable-lightgreen)"
+        return "**Stable**"
+
+    def experimental_md_snippet(self):
+        if self.use_badge:
+            return "![Experimental](https://img.shields.io/badge/-experimental-blue)"
+        return "**Experimental**"
+
+    def deprecated_md_snippet(self):
         if self.use_badge:
-            return self._badge_map
-        return self._label_map
+            return "![Deprecated](https://img.shields.io/badge/-deprecated-red)"
+        return "**Deprecated: {}**"

semantic-conventions/src/tests/data/jinja/attribute_templates/template

@@ -45,7 +45,7 @@ class AttributesTemplate {
   * @deprecated {{attribute_template.brief | to_doc_brief}}.
     {%- endif %}
   */
-    {%- if attribute_template | is_deprecated  %}
+    {%- if attribute_template | is_deprecated %}
   @Deprecated
     {%- endif %}
   public static final AttributeKey<{{ to_java_return_type(attribute_template.instantiated_type | string) | to_camelcase(True)}}> {{attribute_template.fqn | to_const_name}} = {{to_java_key_type(attribute_template.instantiated_type | string)}}("{{attribute_template.fqn}}");
@@ -64,7 +64,7 @@ class AttributesTemplate {
   * @deprecated {{attribute.brief | to_doc_brief}}.
     {%- endif %}
   */
-    {%- if attribute | is_deprecated  %}
+    {%- if attribute | is_deprecated %}
   @Deprecated
     {%- endif %}
   public static final AttributeKey<{{ to_java_return_type(attribute.instantiated_type | string) | to_camelcase(True)}}> {{attribute.fqn | to_const_name}} = {{to_java_key_type(attribute.instantiated_type | string)}}("{{attribute.fqn}}");

semantic-conventions/src/tests/data/markdown/stability/badges_expected.md

@@ -4,7 +4,7 @@
 | Attribute  | Type | Description  | Examples  | Requirement Level |
 |---|---|---|---|---|
 | [`test.def_stability`](labels_expected.md) | boolean |  |  | Required |
-| [`test.deprecated_attr`](labels_expected.md) | boolean |  |  | Required |
+| [`test.deprecated_attr`](labels_expected.md) | boolean | ![Deprecated](https://img.shields.io/badge/-deprecated-red)<br> |  | Required |
 | [`test.exp_attr`](labels_expected.md) | boolean |  |  | Required |
 | [`test.stable_attr`](labels_expected.md) | boolean | ![Stable](https://img.shields.io/badge/-stable-lightgreen)<br> |  | Required |
 <!-- endsemconv -->

semantic-conventions/src/tests/data/markdown/stability/labels_expected.md

@@ -4,7 +4,7 @@
 | Attribute  | Type | Description  | Examples  | Requirement Level |
 |---|---|---|---|---|
 | [`test.def_stability`](labels_expected.md) | boolean |  |  | Required |
-| [`test.deprecated_attr`](labels_expected.md) | boolean |  |  | Required |
+| [`test.deprecated_attr`](labels_expected.md) | boolean | **Deprecated: Removed.**<br> |  | Required |
 | [`test.exp_attr`](labels_expected.md) | boolean |  |  | Required |
 | [`test.stable_attr`](labels_expected.md) | boolean |  |  | Required |
 <!-- endsemconv -->

semantic-conventions/src/tests/data/markdown/stability/stability.yaml

@@ -17,7 +17,8 @@ groups:
       - id: deprecated_attr
         type: boolean
         requirement_level: required
-        stability: deprecated
+        stability: stable
+        deprecated: "Removed."
         brief: ""
       - id: def_stability
         type: boolean

semantic-conventions/src/tests/data/yaml/stability.yaml

@@ -2,7 +2,7 @@ groups:
   - id: test
     type: span
     brief: 'test'
-    prefix: http
+    prefix: http_1
     attributes:
       - id: exp_attr
         type: boolean
@@ -14,11 +14,6 @@ groups:
         requirement_level: required
         stability: stable
         brief: ""
-      - id: deprecated_attr
-        type: boolean
-        requirement_level: required
-        stability: deprecated
-        brief: ""
       - id: def_stability
         type: boolean
         requirement_level: required
@@ -27,7 +22,7 @@ groups:
   - id: parent_default
     type: span
     brief: 'test'
-    prefix: http
+    prefix: http_2
     stability: experimental
     attributes:
       - id: test_attr
@@ -43,19 +38,25 @@ groups:
   - id: not_fail
     type: span
     brief: 'test'
-    prefix: http
-    stability: deprecated
+    prefix: http_3
+    stability: experimental
     attributes:
       - id: test_attr
         type: boolean
         requirement_level: required
         deprecated: should not fail.
         brief: ""
+      - id: stable_deprecated_attr
+        type: boolean
+        requirement_level: required
+        stability: stable
+        deprecated: "should not fail."
+        brief: ""
 
   - id: resource_test
     type: resource
     brief: 'test'
-    prefix: http
+    prefix: http_4
     attributes:
       - id: exp_attr
         type: boolean
@@ -67,11 +68,6 @@ groups:
         requirement_level: required
         stability: stable
         brief: ""
-      - id: deprecated_attr
-        type: boolean
-        requirement_level: required
-        stability: deprecated
-        brief: ""
       - id: def_stability
         type: boolean
         requirement_level: required
@@ -80,7 +76,7 @@ groups:
   - id: resource_parent_default
     type: resource
     brief: 'test'
-    prefix: http
+    prefix: http_5
     stability: experimental
     attributes:
       - id: test_attr
@@ -96,8 +92,7 @@ groups:
   - id: resource_not_fail
     type: resource
     brief: 'test'
-    prefix: http
-    stability: deprecated
+    prefix: http_6
     attributes:
       - id: test_attr
         type: boolean