add stability column to enum members table

open-telemetry · Mar 11, 2024 · 9285e0e · 9285e0e
1 parent 60b3a4f
commit 9285e0e
Show file tree

Hide file tree

Showing 15 changed files with 259 additions and 228 deletions.
diff --git a/semantic-conventions/src/opentelemetry/semconv/templating/markdown/__init__.py b/semantic-conventions/src/opentelemetry/semconv/templating/markdown/__init__.py
@@ -39,12 +39,9 @@
 from opentelemetry.semconv.model.utils import ID_RE
 from opentelemetry.semconv.templating.markdown.options import MarkdownOptions
 
-<<<<<<< HEAD
 from .utils import VisualDiffer
 
-=======
 _OPENTELEMETRY_IO_SPEC_URL = "https://opentelemetry.io/docs/specs/"
->>>>>>> 01b82d1 (lint)
 _REQUIREMENT_LEVEL_URL = (
     _OPENTELEMETRY_IO_SPEC_URL + "semconv/general/attribute-requirement-level/"
 )
@@ -130,14 +127,7 @@ def to_markdown_attr(
             if isinstance(attribute.attr_type, EnumAttributeType)
             else AttributeType.get_instantiated_type(attribute.attr_type)
         )
-<<<<<<< HEAD
-        description = (
-            self._description_with_badge(attribute.stability, attribute.deprecated)
-            + attribute.brief
-        )
-=======
         description = attribute.brief
->>>>>>> c5a1094 (add stability as a separate column)
         if attribute.note:
             self.render_ctx.add_note(attribute.note)
             description += f" [{len(self.render_ctx.notes)}]"
@@ -338,20 +328,18 @@ def to_markdown_enum(self, output: io.StringIO):
             else:
                 output.write("MUST be one of the following:")
             output.write("\n\n")
-            output.write("| Value  | Description |\n|---|---|")
+            output.write("| Value  | Description | Stability |\n|---|---|---|")
             member: EnumMember
             counter = 1
             notes = []
             for member in enum.members:
-                description = (
-                    self._description_with_badge(member.stability, member.deprecated)
-                    + member.brief
-                )
+                description = member.brief
                 if member.note:
                     description += f" [{counter}]"
                     counter += 1
                     notes.append(member.note)
-                output.write(f"\n| `{member.value}` | {description} |")
+                stability = self._render_stability(member)
+                output.write(f"\n| `{member.value}` | {description} | {stability} |")
             counter = 1
             if not notes:
                 output.write("\n")
@@ -548,7 +536,7 @@ def _render_group(self, semconv, parameters, output):
         output.write("<!-- endsemconv -->")
 
     def _render_stability(
-        self, item: typing.Union[SemanticAttribute | BaseSemanticConvention]
+        self, item: typing.Union[SemanticAttribute | BaseSemanticConvention | EnumMember]
     ):
         if item.deprecated:
             return self.options.deprecated_md_snippet(item.deprecated)

diff --git a/semantic-conventions/src/tests/data/markdown/deprecated/expected.md b/semantic-conventions/src/tests/data/markdown/deprecated/expected.md
@@ -18,13 +18,13 @@
 
 `http.flavor` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.
 
-| Value  | Description |
-|---|---|
-| `1.0` | HTTP 1.0 |
-| `1.1` | HTTP 1.1 |
-| `2.0` | HTTP 2 |
-| `SPDY` | SPDY protocol. |
-| `QUIC` | QUIC protocol. |
+| Value  | Description | Stability |
+|---|---|---|
+| `1.0` | HTTP 1.0 | Experimental |
+| `1.1` | HTTP 1.1 | Experimental |
+| `2.0` | HTTP 2 | Experimental |
+| `SPDY` | SPDY protocol. | Experimental |
+| `QUIC` | QUIC protocol. | Experimental |
 <!-- endsemconv -->
 
 It is recommended to also use the general [network attributes][], especially `net.peer.ip`. If `net.transport` is not specified, it can be assumed to be `IP.TCP` except if `http.flavor` is `QUIC`, in which case `IP.UDP` is assumed.

diff --git a/semantic-conventions/src/tests/data/markdown/enum_int/expected.md b/semantic-conventions/src/tests/data/markdown/enum_int/expected.md
@@ -7,23 +7,23 @@
 
 `rpc.grpc.status_code` MUST be one of the following:
 
-| Value  | Description |
-|---|---|
-| `0` | ok |
-| `1` | cancelled |
-| `2` | unknown |
-| `3` | invalid_argument |
-| `4` | deadline_exceeded |
-| `5` | not_found |
-| `6` | already_exists |
-| `7` | permission_denied |
-| `8` | resource_exhausted |
-| `9` | failed_precondition |
-| `10` | aborted |
-| `11` | out_of_range |
-| `12` | unimplemented |
-| `13` | internal |
-| `14` | unavailable |
-| `15` | data_loss |
-| `16` | unauthenticated |
+| Value  | Description | Stability |
+|---|---|---|
+| `0` | ok | Experimental |
+| `1` | cancelled | Experimental |
+| `2` | unknown | Experimental |
+| `3` | invalid_argument | Experimental |
+| `4` | deadline_exceeded | Experimental |
+| `5` | not_found | Experimental |
+| `6` | already_exists | Experimental |
+| `7` | permission_denied | Experimental |
+| `8` | resource_exhausted | Experimental |
+| `9` | failed_precondition | Experimental |
+| `10` | aborted | Experimental |
+| `11` | out_of_range | Experimental |
+| `12` | unimplemented | Experimental |
+| `13` | internal | Experimental |
+| `14` | unavailable | Experimental |
+| `15` | data_loss | Experimental |
+| `16` | unauthenticated | Experimental |
 <!-- endsemconv -->
diff --git a/semantic-conventions/src/tests/data/markdown/extend_constraint/expected.md b/semantic-conventions/src/tests/data/markdown/extend_constraint/expected.md
@@ -57,51 +57,51 @@ Some database systems may allow a connection to switch to a different `db.user`,
 
 `db.system` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.
 
-| Value  | Description |
-|---|---|
-| `other_sql` | Some other SQL database. Fallback only. See notes. |
-| `mssql` | Microsoft SQL Server |
-| `mysql` | MySQL |
-| `oracle` | Oracle Database |
-| `db2` | IBM Db2 |
-| `postgresql` | PostgreSQL |
-| `redshift` | Amazon Redshift |
-| `hive` | Apache Hive |
-| `cloudscape` | Cloudscape |
-| `hsqlsb` | HyperSQL DataBase |
-| `progress` | Progress Database |
-| `maxdb` | SAP MaxDB |
-| `hanadb` | SAP HANA |
-| `ingres` | Ingres |
-| `firstsql` | FirstSQL |
-| `edb` | EnterpriseDB |
-| `cache` | InterSystems Caché |
-| `adabas` | Adabas (Adaptable Database System) |
-| `firebird` | Firebird |
-| `derby` | Apache Derby |
-| `filemaker` | FileMaker |
-| `informix` | Informix |
-| `instantdb` | InstantDB |
-| `interbase` | InterBase |
-| `mariadb` | MariaDB |
-| `netezza` | Netezza |
-| `pervasive` | Pervasive PSQL |
-| `pointbase` | PointBase |
-| `sqlite` | SQLite |
-| `sybase` | Sybase |
-| `teradata` | Teradata |
-| `vertica` | Vertica |
-| `h2` | H2 |
-| `coldfusion` | ColdFusion IMQ |
-| `cassandra` | Apache Cassandra |
-| `hbase` | Apache HBase |
-| `mongodb` | MongoDB |
-| `redis` | Redis |
-| `couchbase` | Couchbase |
-| `couchdb` | CouchDB |
-| `cosmosdb` | Microsoft Azure Cosmos DB |
-| `dynamodb` | Amazon DynamoDB |
-| `neo4j` | Neo4j |
+| Value  | Description | Stability |
+|---|---|---|
+| `other_sql` | Some other SQL database. Fallback only. See notes. | Experimental |
+| `mssql` | Microsoft SQL Server | Experimental |
+| `mysql` | MySQL | Experimental |
+| `oracle` | Oracle Database | Experimental |
+| `db2` | IBM Db2 | Experimental |
+| `postgresql` | PostgreSQL | Experimental |
+| `redshift` | Amazon Redshift | Experimental |
+| `hive` | Apache Hive | Experimental |
+| `cloudscape` | Cloudscape | Experimental |
+| `hsqlsb` | HyperSQL DataBase | Experimental |
+| `progress` | Progress Database | Experimental |
+| `maxdb` | SAP MaxDB | Experimental |
+| `hanadb` | SAP HANA | Experimental |
+| `ingres` | Ingres | Experimental |
+| `firstsql` | FirstSQL | Experimental |
+| `edb` | EnterpriseDB | Experimental |
+| `cache` | InterSystems Caché | Experimental |
+| `adabas` | Adabas (Adaptable Database System) | Experimental |
+| `firebird` | Firebird | Experimental |
+| `derby` | Apache Derby | Experimental |
+| `filemaker` | FileMaker | Experimental |
+| `informix` | Informix | Experimental |
+| `instantdb` | InstantDB | Experimental |
+| `interbase` | InterBase | Experimental |
+| `mariadb` | MariaDB | Experimental |
+| `netezza` | Netezza | Experimental |
+| `pervasive` | Pervasive PSQL | Experimental |
+| `pointbase` | PointBase | Experimental |
+| `sqlite` | SQLite | Experimental |
+| `sybase` | Sybase | Experimental |
+| `teradata` | Teradata | Experimental |
+| `vertica` | Vertica | Experimental |
+| `h2` | H2 | Experimental |
+| `coldfusion` | ColdFusion IMQ | Experimental |
+| `cassandra` | Apache Cassandra | Experimental |
+| `hbase` | Apache HBase | Experimental |
+| `mongodb` | MongoDB | Experimental |
+| `redis` | Redis | Experimental |
+| `couchbase` | Couchbase | Experimental |
+| `couchdb` | CouchDB | Experimental |
+| `cosmosdb` | Microsoft Azure Cosmos DB | Experimental |
+| `dynamodb` | Amazon DynamoDB | Experimental |
+| `neo4j` | Neo4j | Experimental |
 <!-- endsemconv -->
 
 ### Notes on `db.system`

diff --git a/semantic-conventions/src/tests/data/markdown/extend_constraint/input.md b/semantic-conventions/src/tests/data/markdown/extend_constraint/input.md
@@ -57,51 +57,51 @@ At least one of the following is required:
 
 `db.system` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.
 
-| Value  | Description |
-|---|---|
-| `other_sql` | Some other SQL database. Fallback only. See notes. |
-| `mssql` | Microsoft SQL Server |
-| `mysql` | MySQL |
-| `oracle` | Oracle Database |
-| `db2` | IBM Db2 |
-| `postgresql` | PostgreSQL |
-| `redshift` | Amazon Redshift |
-| `hive` | Apache Hive |
-| `cloudscape` | Cloudscape |
-| `hsqlsb` | HyperSQL DataBase |
-| `progress` | Progress Database |
-| `maxdb` | SAP MaxDB |
-| `hanadb` | SAP HANA |
-| `ingres` | Ingres |
-| `firstsql` | FirstSQL |
-| `edb` | EnterpriseDB |
-| `cache` | InterSystems Caché |
-| `adabas` | Adabas (Adaptable Database System) |
-| `firebird` | Firebird |
-| `derby` | Apache Derby |
-| `filemaker` | FileMaker |
-| `informix` | Informix |
-| `instantdb` | InstantDB |
-| `interbase` | InterBase |
-| `mariadb` | MariaDB |
-| `netezza` | Netezza |
-| `pervasive` | Pervasive PSQL |
-| `pointbase` | PointBase |
-| `sqlite` | SQLite |
-| `sybase` | Sybase |
-| `teradata` | Teradata |
-| `vertica` | Vertica |
-| `h2` | H2 |
-| `coldfusion` | ColdFusion IMQ |
-| `cassandra` | Apache Cassandra |
-| `hbase` | Apache HBase |
-| `mongodb` | MongoDB |
-| `redis` | Redis |
-| `couchbase` | Couchbase |
-| `couchdb` | CouchDB |
-| `cosmosdb` | Microsoft Azure Cosmos DB |
-| `dynamodb` | Amazon DynamoDB |
-| `neo4j` | Neo4j |
+| Value  | Description | Stability |
+|---|---|---|
+| `other_sql` | Some other SQL database. Fallback only. See notes. | Experimental |
+| `mssql` | Microsoft SQL Server | Experimental |
+| `mysql` | MySQL | Experimental |
+| `oracle` | Oracle Database | Experimental |
+| `db2` | IBM Db2 | Experimental |
+| `postgresql` | PostgreSQL | Experimental |
+| `redshift` | Amazon Redshift | Experimental |
+| `hive` | Apache Hive | Experimental |
+| `cloudscape` | Cloudscape | Experimental |
+| `hsqlsb` | HyperSQL DataBase | Experimental |
+| `progress` | Progress Database | Experimental |
+| `maxdb` | SAP MaxDB | Experimental |
+| `hanadb` | SAP HANA | Experimental |
+| `ingres` | Ingres | Experimental |
+| `firstsql` | FirstSQL | Experimental |
+| `edb` | EnterpriseDB | Experimental |
+| `cache` | InterSystems Caché | Experimental |
+| `adabas` | Adabas (Adaptable Database System) | Experimental |
+| `firebird` | Firebird | Experimental |
+| `derby` | Apache Derby | Experimental |
+| `filemaker` | FileMaker | Experimental |
+| `informix` | Informix | Experimental |
+| `instantdb` | InstantDB | Experimental |
+| `interbase` | InterBase | Experimental |
+| `mariadb` | MariaDB | Experimental |
+| `netezza` | Netezza | Experimental |
+| `pervasive` | Pervasive PSQL | Experimental |
+| `pointbase` | PointBase | Experimental |
+| `sqlite` | SQLite | Experimental |
+| `sybase` | Sybase | Experimental |
+| `teradata` | Teradata | Experimental |
+| `vertica` | Vertica | Experimental |
+| `h2` | H2 | Experimental |
+| `coldfusion` | ColdFusion IMQ | Experimental |
+| `cassandra` | Apache Cassandra | Experimental |
+| `hbase` | Apache HBase | Experimental |
+| `mongodb` | MongoDB | Experimental |
+| `redis` | Redis | Experimental |
+| `couchbase` | Couchbase | Experimental |
+| `couchdb` | CouchDB | Experimental |
+| `cosmosdb` | Microsoft Azure Cosmos DB | Experimental |
+| `dynamodb` | Amazon DynamoDB | Experimental |
+| `neo4j` | Neo4j | Experimental |
 <!-- endsemconv -->
 
 ### Notes on `db.system`

diff --git a/semantic-conventions/src/tests/data/markdown/include/expected.md b/semantic-conventions/src/tests/data/markdown/include/expected.md
@@ -35,11 +35,11 @@
 
 `faas.trigger` MUST be one of the following:
 
-| Value  | Description |
-|---|---|
-| `datasource` | A response to some data source operation such as a database or filesystem read/write. |
-| `http` | To provide an answer to an inbound HTTP request |
-| `pubsub` | A function is set to be executed when messages are sent to a messaging system. |
-| `timer` | A function is scheduled to be executed regularly. |
-| `other` | other |
+| Value  | Description | Stability |
+|---|---|---|
+| `datasource` | A response to some data source operation such as a database or filesystem read/write. | Experimental |
+| `http` | To provide an answer to an inbound HTTP request | Experimental |
+| `pubsub` | A function is set to be executed when messages are sent to a messaging system. | Experimental |
+| `timer` | A function is scheduled to be executed regularly. | Experimental |
+| `other` | other | Experimental |
 <!-- endsemconv -->
diff --git a/semantic-conventions/src/tests/data/markdown/multiple_enum/expected.md b/semantic-conventions/src/tests/data/markdown/multiple_enum/expected.md
@@ -20,33 +20,33 @@
 
 `net.host.connection.subtype` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.
 
-| Value  | Description |
-|---|---|
-| `1G` | 1G |
-| `2G` | 2G |
+| Value  | Description | Stability |
+|---|---|---|
+| `1G` | 1G | Experimental |
+| `2G` | 2G | Experimental |
 
 `net.host.connection.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.
 
-| Value  | Description |
-|---|---|
-| `wifi` | wifi [1] |
-| `wired` | wired |
-| `cell` | cell |
-| `unavailable` | unavailable |
+| Value  | Description | Stability |
+|---|---|---|
+| `wifi` | wifi [1] | Experimental |
+| `wired` | wired | Experimental |
+| `cell` | cell | Experimental |
+| `unavailable` | unavailable | Experimental |
 
 **[1]:** Usually 802.11
 
 `net.transport` MUST be one of the following:
 
-| Value  | Description |
-|---|---|
-| `IP.TCP` | ip.tcp |
-| `IP.UDP` | ip.udp |
-| `IP` | Another IP-based protocol |
-| `Unix` | Unix Domain socket. See below. |
-| `pipe` | Named or anonymous pipe. See note below. |
-| `inproc` | In-process communication. [1] |
-| `other` | Something else (non IP-based). |
+| Value  | Description | Stability |
+|---|---|---|
+| `IP.TCP` | ip.tcp | Experimental |
+| `IP.UDP` | ip.udp | Experimental |
+| `IP` | Another IP-based protocol | Experimental |
+| `Unix` | Unix Domain socket. See below. | Experimental |
+| `pipe` | Named or anonymous pipe. See note below. | Experimental |
+| `inproc` | In-process communication. [1] | Experimental |
+| `other` | Something else (non IP-based). | Experimental |
 
 **[1]:** Signals that there is only in-process communication not using a "real" network protocol in cases where network attributes would normally be expected. Usually all other network attributes can be left out in that case.
 <!-- endsemconv -->