Update documentation for how to cut a release AND perform the action … (#190)

Co-authored-by: Armin Ruech <armin.ruech@dynatrace.com>

CHANGELOG.md

@@ -7,6 +7,8 @@ release.
 
 ## Unreleased
 
+## v1.21.0 (2023-07-13)
+
 Note: This is the first release of Semantic Conventions separate from the Specification.
 
 - Add GCP Bare Metal Solution as a cloud platform

CONTRIBUTING.md

@@ -122,3 +122,18 @@ make misspell-correction
 3. Modify `LATEST_SPECIFICATION_VERSION` to the latest specification tag, e.g. `1.21`
 4. Run the script from the root directory, e.g. `semantic-conventions$ ./internal/tools/update_specification_version.sh`.
 5. Add all modified files to the change submit and submit a PR.
+
+## Making a Release
+
+- Ensure the referenced specification version is up to date.  Use
+  [tooling to update the spec](#updating-the-referenced-specification-version)
+  if needed.
+- Create a staging branch for the release.
+  - Update `schema-next.yaml` file and move to `schemas/{version}`
+    - Ensure the `next` version is appropriately configured as the `{version}`.
+    - Copy `schema-next.yaml` to `schemas/{version}`.
+    - Add `next` as a version in `schema-next.yaml` version.
+  - Update `CHANGELOG.md` for the latest version.
+    - Add `## v{version} ({date})` under `## Unreleased`
+  - Send staging tag as PR for review.
+- Create a tag `v{version}` on the merged PR and push remote.

README.md

@@ -11,12 +11,6 @@ This repository is currently using [this specification version][SpecificationVer
 
 The documentation currently resides in the [doc](docs/README.md) folder.
 
-## TODOs
-
-- [ ] Set up SchemaURL publication
-- [ ] Contributing.MD document
-- [ ] Restructure markdown for easier consumption.
-
 ## Contributing
 
 See [CONTRIBUTING.md](CONTRIBUTING.md)

internal/tools/schema_check.sh

@@ -32,12 +32,15 @@ grep -o -e '## v[1-9].*\s' $root_dir/CHANGELOG.md | grep -o '[1-9].*' | while re
     exit 3
   fi
 
-  curl --no-progress-meter https://opentelemetry.io/schemas/$ver > verify$ver
+  # Schema file will no be served directly from this repository when linked
-
+  # into opentelemetry.io.  We disable this for now and need to move the check
-  diff verify$ver $file && echo "Published schema at https://opentelemetry.io/schemas/$ver is correct" \
+  # into the website.
-    || (echo "Published schema at https://opentelemetry.io/schemas/$ver is incorrect!" && exit 3)
+  # curl --no-progress-meter https://opentelemetry.io/schemas/$ver > verify$ver
-
+  #
-  rm verify$ver
+  # diff verify$ver $file && echo "Published schema at https://opentelemetry.io/schemas/$ver is correct" \
+  #   || (echo "Published schema at https://opentelemetry.io/schemas/$ver is incorrect!" && exit 3)
+  #
+  # rm verify$ver
 done
 
 # Now check the content of all schema files in the ../shemas directory.

schema-next.yaml

@@ -0,0 +1,139 @@
+file_format: 1.1.0
+schema_url: https://opentelemetry.io/schemas/1.21.0
+versions:
+  next:
+  1.21.0:
+    spans:
+      changes:
+        # https://github.com/open-telemetry/opentelemetry-specification/pull/3336
+        - rename_attributes:
+            attribute_map:
+              messaging.kafka.client_id: messaging.client_id
+              messaging.rocketmq.client_id: messaging.client_id
+        # https://github.com/open-telemetry/opentelemetry-specification/pull/3402
+        - rename_attributes:
+            attribute_map:
+              # net.peer.(name|port) attributes were usually populated on client side
+              # so they should be usually translated to server.(address|port)
+              # net.host.* attributes were only populated on server side
+              net.host.name: server.address
+              net.host.port: server.port
+              # was only populated on client side
+              net.sock.peer.name: server.socket.domain
+              # net.sock.peer.(addr|port) mapping is not possible
+              # since they applied to both client and server side
+              # were only populated on server side
+              net.sock.host.addr: server.socket.address
+              net.sock.host.port: server.socket.port
+              http.client_ip: client.address
+        # https://github.com/open-telemetry/opentelemetry-specification/pull/3426
+        - rename_attributes:
+            attribute_map:
+              net.protocol.name: network.protocol.name
+              net.protocol.version: network.protocol.version
+              net.host.connection.type: network.connection.type
+              net.host.connection.subtype: network.connection.subtype
+              net.host.carrier.name: network.carrier.name
+              net.host.carrier.mcc: network.carrier.mcc
+              net.host.carrier.mnc: network.carrier.mnc
+              net.host.carrier.icc: network.carrier.icc
+        # https://github.com/open-telemetry/opentelemetry-specification/pull/3355
+        - rename_attributes:
+            attribute_map:
+              http.method: http.request.method
+              http.status_code: http.response.status_code
+              http.scheme: url.scheme
+              http.url: url.full
+              http.request_content_length: http.request.body.size
+              http.response_content_length: http.response.body.size
+    metrics:
+      changes:
+        # https://github.com/open-telemetry/semantic-conventions/pull/53
+        - rename_metrics:
+            process.runtime.jvm.cpu.utilization: process.runtime.jvm.cpu.recent_utilization
+  1.20.0:
+    spans:
+      changes:
+        # https://github.com/open-telemetry/opentelemetry-specification/pull/3272
+        - rename_attributes:
+            attribute_map:
+              net.app.protocol.name: net.protocol.name
+              net.app.protocol.version: net.protocol.version
+  1.19.0:
+    spans:
+      changes:
+        # https://github.com/open-telemetry/opentelemetry-specification/pull/3209
+        - rename_attributes:
+            attribute_map:
+              faas.execution: faas.invocation_id
+        # https://github.com/open-telemetry/opentelemetry-specification/pull/3188
+        - rename_attributes:
+            attribute_map:
+              faas.id: cloud.resource_id
+        # https://github.com/open-telemetry/opentelemetry-specification/pull/3190
+        - rename_attributes:
+            attribute_map:
+              http.user_agent: user_agent.original
+    resources:
+      changes:
+        # https://github.com/open-telemetry/opentelemetry-specification/pull/3190
+        - rename_attributes:
+            attribute_map:
+              browser.user_agent: user_agent.original
+  1.18.0:
+  1.17.0:
+    spans:
+      changes:
+        # https://github.com/open-telemetry/opentelemetry-specification/pull/2957
+        - rename_attributes:
+            attribute_map:
+              messaging.consumer_id: messaging.consumer.id
+              messaging.protocol: net.app.protocol.name
+              messaging.protocol_version: net.app.protocol.version
+              messaging.destination: messaging.destination.name
+              messaging.temp_destination: messaging.destination.temporary
+              messaging.destination_kind: messaging.destination.kind
+              messaging.message_id: messaging.message.id
+              messaging.conversation_id: messaging.message.conversation_id
+              messaging.message_payload_size_bytes: messaging.message.payload_size_bytes
+              messaging.message_payload_compressed_size_bytes: messaging.message.payload_compressed_size_bytes
+              messaging.rabbitmq.routing_key: messaging.rabbitmq.destination.routing_key
+              messaging.kafka.message_key: messaging.kafka.message.key
+              messaging.kafka.partition: messaging.kafka.destination.partition
+              messaging.kafka.tombstone: messaging.kafka.message.tombstone
+              messaging.rocketmq.message_type: messaging.rocketmq.message.type
+              messaging.rocketmq.message_tag: messaging.rocketmq.message.tag
+              messaging.rocketmq.message_keys: messaging.rocketmq.message.keys
+              messaging.kafka.consumer_group: messaging.kafka.consumer.group
+  1.16.0:
+  1.15.0:
+    spans:
+      changes:
+        # https://github.com/open-telemetry/opentelemetry-specification/pull/2743
+        - rename_attributes:
+            attribute_map:
+              http.retry_count: http.resend_count
+  1.14.0:
+  1.13.0:
+    spans:
+      changes:
+        # https://github.com/open-telemetry/opentelemetry-specification/pull/2614
+        - rename_attributes:
+            attribute_map:
+              net.peer.ip: net.sock.peer.addr
+              net.host.ip: net.sock.host.addr
+  1.12.0:
+  1.11.0:
+  1.10.0:
+  1.9.0:
+  1.8.0:
+    spans:
+      changes:
+        - rename_attributes:
+            attribute_map:
+              db.cassandra.keyspace: db.name
+              db.hbase.namespace: db.name
+  1.7.0:
+  1.6.1:
+  1.5.0:
+  1.4.0: