Review feedback

Author: thompson-tomo

.textlintrc.yml

@@ -24,6 +24,9 @@ rules:
   terminology:
     defaultTerms: true
     skip: []
+    exclude:
+      - 'readme(s)?'
+      - 'to-?do(s)?(?=[ ,.])'
     terms:
       - Actix
       - Ajax
@@ -87,6 +90,7 @@ rules:
       - Python
       - Quarkus
       - Rails
+      - README
       - Redis
       - Ruby
       - Rust
@@ -99,6 +103,7 @@ rules:
       - Thanos
       - Traefik
       - TypeScript
+      - UNIX
       - URL
       - WordPress
       - WSGI
@@ -169,6 +174,7 @@ rules:
       - [repos, repositories]
       - ['screen[- ]shot(s)?', screenshot$1]
       - ['time[- ]stamp(s)?', timestamp$1]
+      - ["to-?do(s)?", "TODO$1"]
       - ["uid['’]?(s)?", UID$1]
       - ['(walk)-(throughs?)', $1$2] # cSpell:disable-line
       - ['(work)-(arounds?)', $1$2]

CHANGELOG.md

@@ -407,7 +407,7 @@ release.
 - Define syntax for escaping declarative configuration environment variable
   references.
   ([#4375](https://github.com/open-telemetry/opentelemetry-specification/pull/4375))
-- Resolve various declarative config todos.
+- Resolve various declarative config TODOs.
   ([#4394](https://github.com/open-telemetry/opentelemetry-specification/pull/4394))
 
 ## v1.41.0 (2025-01-21)
@@ -799,7 +799,7 @@ release.
   ([#3945](https://github.com/open-telemetry/opentelemetry-specification/pull/3945))
 - Prometheus: represent Prometheus Info, StateSet and Unknown-typed metrics in OTLP.
   ([#3868](https://github.com/open-telemetry/opentelemetry-specification/pull/3868))
-- Update and reorganize the Prometheus sdk exporter specification.
+- Update and reorganize the Prometheus SDK exporter specification.
   ([#3872](https://github.com/open-telemetry/opentelemetry-specification/pull/3872))
 
 ### SDK Configuration
@@ -1478,9 +1478,9 @@ release.
 
 ### Logs
 
-- Update log readme "request context" to "trace context".
+- Update log README "request context" to "trace context".
   ([#3332](https://github.com/open-telemetry/opentelemetry-specification/pull/3332))
-- Remove log readme document status.
+- Remove log README document status.
   ([#3334](https://github.com/open-telemetry/opentelemetry-specification/pull/3334))
 - Break out compatibility document on recording trace context in non-OTLP Log Format
   ([#3331](https://github.com/open-telemetry/opentelemetry-specification/pull/3331))
@@ -1577,7 +1577,7 @@ release.
 
 - Rename Logs API to Logs Bridge API to prevent confusion.
   ([#3197](https://github.com/open-telemetry/opentelemetry-specification/pull/3197))
-- Move event language from log readme to event-api.
+- Move event language from log README to event-api.
   ([#3252](https://github.com/open-telemetry/opentelemetry-specification/pull/3252))
 
 ### Resource
@@ -1603,7 +1603,7 @@ release.
   ([#3250](https://github.com/open-telemetry/opentelemetry-specification/pull/3250))
 - Mark the attribute naming guidelines in the specification as stable.
   ([#3220](https://github.com/open-telemetry/opentelemetry-specification/pull/3220))
-- Mark telemetry schema readme stable.
+- Mark telemetry schema README stable.
   ([#3221](https://github.com/open-telemetry/opentelemetry-specification/pull/3221))
 - Remove mention of `net.transport` from HTTP semantic conventions
   ([#3244](https://github.com/open-telemetry/opentelemetry-specification/pull/3244))
@@ -1938,7 +1938,7 @@ release.
   ([#2874](https://github.com/open-telemetry/opentelemetry-specification/pull/2874))
 - Add `process.paging.faults` metric to semantic conventions
   ([#2827](https://github.com/open-telemetry/opentelemetry-specification/pull/2827))
-- Define semantic conventions yaml for Non-OTLP conventions
+- Define semantic conventions YAML for Non-OTLP conventions
   ([#2850](https://github.com/open-telemetry/opentelemetry-specification/pull/2850))
 - Add more semantic convetion attributes of Apache RocketMQ
   ([#2881](https://github.com/open-telemetry/opentelemetry-specification/pull/2881))
@@ -1990,7 +1990,7 @@ release.
 
 - Add environment variables for configuring the `BatchLogRecordProcessor`.
   ([#2785](https://github.com/open-telemetry/opentelemetry-specification/pull/2785))
-- Fix inconsistencies in log readme
+- Fix inconsistencies in log README
   ([#2800](https://github.com/open-telemetry/opentelemetry-specification/pull/2800)).
 
 ### Resource
@@ -3052,7 +3052,7 @@ Updates:
 - Resource attributes: lowerecased the allowed values of the `aws.ecs.launchtype`
   attribute
   ([#1339](https://github.com/open-telemetry/opentelemetry-specification/pull/1339))
-- Trace Exporters: Fix todos in Jaeger exporter spec
+- Trace Exporters: Fix TODOs in Jaeger exporter spec
   ([#1374](https://github.com/open-telemetry/opentelemetry-specification/pull/1374))
 - Clarify that Jaeger/Zipkin exporters must rely on the default Resource to
   get service.name if none was specified.

oteps/0016-named-tracers.md

@@ -50,7 +50,7 @@ Meter meter = OpenTelemetry.getMeterProvider().getMeter("io.opentelemetry.contri
 
 These factories (`TracerProvider` and `MeterProvider`) replace the global `Tracer` / `Meter` singleton objects as ubiquitous points to request Tracer and Meter instances.
 
- The _name_ used to create a Tracer or Meter must identify the _instrumentation_ libraries (also referred to as _integrations_) and not the library being instrumented. These instrumentation libraries could be libraries developed in an OpenTelemetry repository, a 3rd party implementation, or even auto-injected code (see [OpenTelemetry Without Manual Instrumentation OTEP](https://github.com/open-telemetry/oteps/blob/main/text/0001-telemetry-without-manual-instrumentation.md)). See also the examples for identifiers at the end.
+ The _name_ used to create a Tracer or Meter must identify the _instrumentation_ libraries (also referred to as _integrations_) and not the library being instrumented. These instrumentation libraries could be libraries developed in an OpenTelemetry repository, a third-party implementation, or even auto-injected code (see [OpenTelemetry Without Manual Instrumentation OTEP](https://github.com/open-telemetry/oteps/blob/main/text/0001-telemetry-without-manual-instrumentation.md)). See also the examples for identifiers at the end.
 If a library (or application) has instrumentation built-in, it is both the instrumenting and instrumented library and should pass its own name here. In all other cases (and to distinguish them from that case), the distinction between instrumenting and instrumented library is very important. For example, if an HTTP library `com.example.http` is instrumented by either `io.opentelemetry.contrib.examplehttp`, then it is important that the Tracer is not named `com.example.http`, but `io.opentelemetry.contrib.examplehttp` after the actual instrumentation library.
 
 If no name (null or empty string) is specified, following the suggestions in ["error handling proposal"](https://github.com/open-telemetry/opentelemetry-specification/pull/153), a "smart default" will be applied and a default Tracer / Meter implementation is returned.

oteps/0119-standard-system-metrics.md

@@ -6,7 +6,7 @@ This OTEP is largely based on the existing implementation in the OpenTelemetry C
 
 ## Trade-offs and mitigations
 
-When naming a metric instrument, there is a trade-off between discoverability and ambiguity. For example, a metric called `system.cpu.load_average` is very discoverable, but the meaning of this metric is ambiguous. [Load average](https://en.wikipedia.org/wiki/Load_(computing)) is well defined on Unix, but is not a standard metric on Windows. While discoverability is important, names must be unambiguous.
+When naming a metric instrument, there is a trade-off between discoverability and ambiguity. For example, a metric called `system.cpu.load_average` is very discoverable, but the meaning of this metric is ambiguous. [Load average](https://en.wikipedia.org/wiki/Load_(computing)) is well defined on UNIX, but is not a standard metric on Windows. While discoverability is important, names must be unambiguous.
 
 ## Prior art
 
@@ -151,5 +151,5 @@ Some programming languages have multiple runtime environments that vary signific
 - Should the individual runtimes have their specific naming conventions in the spec?
 - Is it OK to include instruments specific to an OS (or OS family) under a top-level prefix, as long as they are unambiguous? For example, naming inode related instruments, which of the below is preferred?
   1. Top level: `system.filesystem.inodes.*`
-  2. Unix family level: `system.unix.filesystem.inodes.*`
-  3. One for each Unix OS: `system.linux.filesystem.inodes.*`, `system.freebsd.filesystem.inodes.*`, `system.netbsd.filesystem.inodes.*`, etc.
+  2. UNIX family level: `system.unix.filesystem.inodes.*`
+  3. One for each UNIX OS: `system.linux.filesystem.inodes.*`, `system.freebsd.filesystem.inodes.*`, `system.netbsd.filesystem.inodes.*`, etc.

oteps/0122-otlp-http-json.md

@@ -19,7 +19,7 @@ This is a proposal to add HTTP Transport extension supporting JSON serialization
 
 ## Motivation
 
-Protobuf is a relatively big dependency, which some clients are not willing to take. For example, WebJS, iOS/Android (in some scenarios, the size of the installation package is limited, do not want to introduce protobuf dependencies). Plain JSON is a smaller dependency and is built in the standard libraries of many programming languages.
+Protobuf is a relatively big dependency, which some clients are not willing to take. For example, WebJS, iOS/Android (in some scenarios, the size of the installation package is limited, do not want to introduce protobuf dependencies). Plain JSON is a smaller dependency and is built-in the standard libraries of many programming languages.
 
 ## OTLP/HTTP+JSON Protocol Details
 

oteps/0152-telemetry-schemas.md

@@ -1047,7 +1047,7 @@ The downsides are:
 
 ## Prior Art
 
-- [OpenTelemetry Log Data Model: Body metadata](https://docs.google.com/document/d/1ZExye1lW43owwaxcbjOvl0P2qER-UaYd_MyxItc2h0k/edit#)
+- [OpenTelemetry Log Data Model: Body Metadata](https://docs.google.com/document/d/1ZExye1lW43owwaxcbjOvl0P2qER-UaYd_MyxItc2h0k/edit#)
   by Christian Beedgen.
 
 - [Generic event encoding schemas](https://docs.google.com/document/d/11ccT_zBbiCfwKyi6TMuy2sA3nUdElNQsDJOQ79icVKs/edit#)

oteps/0199-support-elastic-common-schema-in-opentelemetry.md

@@ -161,7 +161,7 @@ Example of a NGINX Access Log entry structured with ECS
 | Category | <a href="../specification/logs/data-model.md#log-and-event-record-definition">OTel Logs and Event Record</a> (all or a subset of <a href="https://protobuf.dev/programming-guides/proto3/">GRPC data types</a>) | <a href="https://www.elastic.co/docs/reference/elasticsearch/mapping-reference/field-data-types">ECS Data Types</a> |
 | --- | --- | --- |
 | Text | string | <a href="https://www.elastic.co/docs/reference/elasticsearch/mapping-reference/text#text-field-type">text</a>, <a href="https://www.elastic.co/docs/reference/elasticsearch/mapping-reference/text#match-only-text-field-type">match_only_text</a>, <a href="https://www.elastic.co/docs/reference/elasticsearch/mapping-reference/keyword#keyword-field-type">keyword</a> <a href="https://www.elastic.co/docs/reference/elasticsearch/mapping-reference/keyword#constant-keyword-field-type">constant_keyword</a>, <a href="https://www.elastic.co/docs/reference/elasticsearch/mapping-reference/keyword#wildcard-field-type">wildcard</a> |
-| Dates | uint64 nanoseconds since Unix epoch | <a href="https://www.elastic.co/docs/reference/elasticsearch/mapping-reference/date">date</a>, <a href="https://www.elastic.co/docs/reference/elasticsearch/mapping-reference/date_nanos">date_nanos</a> |
+| Dates | uint64 nanoseconds since UNIX epoch | <a href="https://www.elastic.co/docs/reference/elasticsearch/mapping-reference/date">date</a>, <a href="https://www.elastic.co/docs/reference/elasticsearch/mapping-reference/date_nanos">date_nanos</a> |
 | Numbers | number | <a href="https://www.elastic.co/docs/reference/elasticsearch/mapping-reference/number">long</a>, <a href="https://www.elastic.co/docs/reference/elasticsearch/mapping-reference/number">double</a>, <a href="https://www.elastic.co/docs/reference/elasticsearch/mapping-reference/number">scaled_float</a>, <a href="https://www.elastic.co/docs/reference/elasticsearch/mapping-reference/boolean">boolean</a>… |
 | Objects | uint32, uint64… | <a href="https://www.elastic.co/docs/reference/elasticsearch/mapping-reference/object">object</a> (JSON object), <a href="https://www.elastic.co/docs/reference/elasticsearch/mapping-reference/flattened">flattened</a> (An entire JSON object as a single field value) |
 | Structured Objects | No complex semantic data type specified for the moment (e.g. string is being used for ip addresses rather than having an "ip" data structure in OTel). <br/> Note that OTel supports arrays and nested objects. | <a href="https://www.elastic.co/docs/reference/elasticsearch/mapping-reference/ip">ip</a>, <a href="https://www.elastic.co/docs/reference/elasticsearch/mapping-reference/geo-point">geo_point</a>, <a href="https://www.elastic.co/docs/reference/elasticsearch/mapping-reference/geo-shape">geo_shape</a>, <a href="https://www.elastic.co/docs/reference/elasticsearch/mapping-reference/version">version</a>, <a href="https://www.elastic.co/docs/reference/elasticsearch/mapping-reference/range">long_range</a>, <a href="https://www.elastic.co/docs/reference/elasticsearch/mapping-reference/range">date_range</a>, <a href="https://www.elastic.co/docs/reference/elasticsearch/mapping-reference/range">ip_range</a> |
@@ -185,7 +185,7 @@ As the markdown code of the tables is hard to read and maintain with very long l
    </td>
   </tr>
   <tr>
-   <td><a href="../specification/logs/data-model.md#log-and-event-record-definition">Timestamp</a> (uint64 nanoseconds since Unix epoch)
+   <td><a href="../specification/logs/data-model.md#log-and-event-record-definition">Timestamp</a> (uint64 nanoseconds since UNIX epoch)
    </td>
    <td><a href="https://www.elastic.co/docs/reference/ecs/ecs-base#field-timestamp">@timestamp</a> (date)
    </td>

oteps/0225-configuration.md

@@ -299,7 +299,7 @@ In choosing to recommend JSON schema, the working group looked at the following
 * [Cue](https://cuelang.org/) - A promising simpler language to define a schema, the working group decided against CUE because:
   * Tooling available for validating CUE files in languages outside of Go were limited.
   * Familiarity and learning curve would create problems for both users and contributors of OpenTelemetry.
-* [Protobuf](https://protobuf.dev) - With protobuf already used heavily in OpenTelemetry, the format was worth investigating as an option to define the schema. The working group decided against Protobuf because:
+* [Protobuf](https://protobuf.dev) - With protobuf already used heavily in OpenTelemetry, the format was worth investigating as an option to define the schema. The working group decided against protobuf because:
   * Validation errors are the result of serialization errors which can be difficult to interpret.
   * Limitations in the schema definition language result in poor ergonomics if type safety is to be retained.
 

oteps/0258-env-context-baggage-carriers.md

@@ -11,7 +11,7 @@ processes.
   * [Example Context](#example-context)
     * [Distributed Tracing in OpenTofu Prototype Example](#distributed-tracing-in-opentofu-prototype-example)
 * [Core Specification Changes](#core-specification-changes)
-  * [Unix](#unix-limitations)
+  * [UNIX](#unix-limitations)
   * [Windows](#windows-limitations)
   * [Allowed Characters](#allowed-characters)
 * [Trade-offs and Mitigations](#trade-offs-and-mitigations)
@@ -199,9 +199,9 @@ variables for the carrier that align with context propagator specifications.
 [python-env]: https://github.com/Div95/opentelemetry-python/tree/feature/env_propagator/propagator/opentelemetry-propagator-env
 [swift-env]: https://github.com/open-telemetry/opentelemetry-swift-core/blob/c84cdc1760e20fc3a448c4e8aaae490f7d48ac67/Sources/OpenTelemetrySdk/Trace/Propagation/EnvironmentContextPropagator.swift
 
-### Unix Limitations
+### UNIX Limitations
 
-Unix system utilities use upper-case for environment variables and lower-case
+UNIX system utilities use upper-case for environment variables and lower-case
 are reserved for applications. Using upper-case will prevent conflicts with
 internal application variables.
 

oteps/entities/0256-entities-data-model.md

@@ -689,7 +689,7 @@ type used by the ID field, which is more restricted in the shape.
 Are we happy with this discrepancy?
 
 Here is corresponding
-[Todo item](https://github.com/orgs/open-telemetry/projects/85/views/1?pane=issue&itemId=62411493).
+[TODO item](https://github.com/orgs/open-telemetry/projects/85/views/1?pane=issue&itemId=62411493).
 
 ### Classes of Entity Types
 
@@ -698,7 +698,7 @@ and non-infrastructure entities (logical entities) such as Service? Is this dist
 important?
 
 Here is corresponding
-[Todo item](https://github.com/orgs/open-telemetry/projects/85/views/1?pane=issue&itemId=62411407).
+[TODO item](https://github.com/orgs/open-telemetry/projects/85/views/1?pane=issue&itemId=62411407).
 
 ### Multiple Observers
 
@@ -733,7 +733,7 @@ events that contain the same ObserverId value will overwrite attributes from the
 reporting of the EntityState event from that observer.
 
 Here is corresponding
-[Todo item](https://github.com/orgs/open-telemetry/projects/85/views/1?pane=issue&itemId=62411289).
+[TODO item](https://github.com/orgs/open-telemetry/projects/85/views/1?pane=issue&itemId=62411289).
 
 ### Is Type part of Entity's identity?
 
@@ -750,7 +750,7 @@ entity that describes the Collector has some other attribute in its ID (for exam
 `agent.type` attribute [if it gets accepted](https://github.com/open-telemetry/semantic-conventions/pull/950)).
 
 Here is corresponding
-[Todo item](https://github.com/orgs/open-telemetry/projects/85?pane=issue&itemId=57053320).
+[TODO item](https://github.com/orgs/open-telemetry/projects/85?pane=issue&itemId=57053320).
 
 ### Choosing from Multiple IDs
 
@@ -762,7 +762,7 @@ We need to provide a recommendation for the cases when more than one valid ident
 exists about how to make a choice between the identifiers.
 
 Here is corresponding
-[Todo item](https://github.com/orgs/open-telemetry/projects/85?pane=issue&itemId=57053415).
+[TODO item](https://github.com/orgs/open-telemetry/projects/85?pane=issue&itemId=57053415).
 
 ## Future Work