diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4e5f06a1..8b99b52a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -306,6 +306,55 @@ tracer_provider: [Schema validation](#schema-validation) project tooling enforces that types labeled `isSdkExtensionPlugin: true` are modeled consistently as described above. +### Deprecating properties and types + +Properties and types that are no longer recommended for use should be deprecated rather than removed. Per the [versioning policy](VERSIONING.md), no existing type or type property may be deleted in a `MINOR` version. Deprecated properties and types must therefore be kept until at least the next `MAJOR` version. + +This guidance does not apply to [experimental features](VERSIONING.md#experimental-features), which are exempt from versioning policy guarantees and may be removed in `MINOR` versions without deprecation. + +To deprecate a property or type: + +1. Set [`deprecated: true`](https://json-schema.org/understanding-json-schema/reference/annotations) on the property or type in the YAML source. +2. Update the `description` to include a bold `**Deprecated**` notice that: + * States the first `MINOR` version in which the deprecation appears and the earliest `MAJOR` version in which it may be removed (e.g. "as of v1.2.0, may be removed in v2.0.0"). + * Explains why the property or type is deprecated, including a link to the relevant specification change. + * Advises that SDKs MAY continue to support the property for backwards compatibility and that new configurations SHOULD NOT use it. +3. Add a CHANGELOG entry. + +For example, a deprecated property in YAML source: + +```yaml +opencensus: + $ref: "#/$defs/OpenCensusMetricProducer" + deprecated: true + description: | + Configure metric producer to be opencensus. + + **Deprecated** as of v1.2.0, may be removed in v2.0.0. The OpenCensus + compatibility specification it relies on was deprecated in + https://github.com/open-telemetry/opentelemetry-specification/pull/5138. + SDKs MAY continue to support this entry for backwards compatibility; + new configurations SHOULD NOT use it. + defaultBehavior: ignore +``` + +And a deprecated type: + +```yaml +OpenCensusMetricProducer: + type: + - object + - "null" + additionalProperties: false + deprecated: true + description: | + **Deprecated** as of v1.2.0, may be removed in v2.0.0. The OpenCensus + compatibility specification it relies on was deprecated in + https://github.com/open-telemetry/opentelemetry-specification/pull/5138. + See also the + [OpenCensus sunset announcement](https://opentelemetry.io/blog/2023/sunsetting-opencensus/). +``` + ## Project tooling This repository has a variety of tooling assisting with the development of the JSON schema and associated artifacts. diff --git a/opentelemetry_configuration.json b/opentelemetry_configuration.json index cd508d32..7a8e7975 100644 --- a/opentelemetry_configuration.json +++ b/opentelemetry_configuration.json @@ -1673,7 +1673,7 @@ "opencensus": { "$ref": "#/$defs/OpenCensusMetricProducer", "deprecated": true, - "description": "Configure metric producer to be opencensus.\n\n**Deprecated** as of June 2026. The OpenCensus compatibility\nspecification it relies on was deprecated in\nhttps://github.com/open-telemetry/opentelemetry-specification/pull/5138.\nSDKs MAY continue to support this entry for backwards compatibility;\nnew configurations SHOULD NOT use it.\nIf omitted, ignore.\n" + "description": "Configure metric producer to be opencensus.\n\n**Deprecated** as of v1.2.0, may be removed in v2.0.0. The OpenCensus\ncompatibility specification it relies on was deprecated in\nhttps://github.com/open-telemetry/opentelemetry-specification/pull/5138.\nSDKs MAY continue to support this entry for backwards compatibility;\nnew configurations SHOULD NOT use it.\nIf omitted, ignore.\n" } } }, @@ -1721,7 +1721,7 @@ ], "additionalProperties": false, "deprecated": true, - "description": "**Deprecated** as of June 2026. The OpenCensus compatibility specification\nit relies on was deprecated in\nhttps://github.com/open-telemetry/opentelemetry-specification/pull/5138.\nSee also the\n[OpenCensus sunset announcement](https://opentelemetry.io/blog/2023/sunsetting-opencensus/).\n" + "description": "**Deprecated** as of v1.2.0, may be removed in v2.0.0. The OpenCensus\ncompatibility specification it relies on was deprecated in\nhttps://github.com/open-telemetry/opentelemetry-specification/pull/5138.\nSee also the\n[OpenCensus sunset announcement](https://opentelemetry.io/blog/2023/sunsetting-opencensus/).\n" }, "OtlpGrpcExporter": { "type": [ diff --git a/schema-docs.md b/schema-docs.md index f6f1df6a..7ae940bf 100644 --- a/schema-docs.md +++ b/schema-docs.md @@ -1850,7 +1850,7 @@ No snippets. | Property | Type | Required? | Default and Null Behavior | Constraints | Description | |---|---|---|---|---|---| -| `opencensus` | [`OpenCensusMetricProducer`](#opencensusmetricproducer) | `false` | If omitted, ignore. | No constraints. | Configure metric producer to be opencensus.

**Deprecated** as of June 2026. The OpenCensus compatibility
specification it relies on was deprecated in
https://github.com/open-telemetry/opentelemetry-specification/pull/5138.
SDKs MAY continue to support this entry for backwards compatibility;
new configurations SHOULD NOT use it.
| +| `opencensus` | [`OpenCensusMetricProducer`](#opencensusmetricproducer) | `false` | If omitted, ignore. | No constraints. | Configure metric producer to be opencensus.

**Deprecated** as of v1.2.0, may be removed in v2.0.0. The OpenCensus
compatibility specification it relies on was deprecated in
https://github.com/open-telemetry/opentelemetry-specification/pull/5138.
SDKs MAY continue to support this entry for backwards compatibility;
new configurations SHOULD NOT use it.
|
Language support status @@ -1891,7 +1891,7 @@ No snippets. "opencensus": { "$ref": "#/$defs/OpenCensusMetricProducer", "deprecated": true, - "description": "Configure metric producer to be opencensus.\n\n**Deprecated** as of June 2026. The OpenCensus compatibility\nspecification it relies on was deprecated in\nhttps://github.com/open-telemetry/opentelemetry-specification/pull/5138.\nSDKs MAY continue to support this entry for backwards compatibility;\nnew configurations SHOULD NOT use it.\nIf omitted, ignore.\n" + "description": "Configure metric producer to be opencensus.\n\n**Deprecated** as of v1.2.0, may be removed in v2.0.0. The OpenCensus\ncompatibility specification it relies on was deprecated in\nhttps://github.com/open-telemetry/opentelemetry-specification/pull/5138.\nSDKs MAY continue to support this entry for backwards compatibility;\nnew configurations SHOULD NOT use it.\nIf omitted, ignore.\n" } } } @@ -2029,7 +2029,7 @@ No snippets. ], "additionalProperties": false, "deprecated": true, - "description": "**Deprecated** as of June 2026. The OpenCensus compatibility specification\nit relies on was deprecated in\nhttps://github.com/open-telemetry/opentelemetry-specification/pull/5138.\nSee also the\n[OpenCensus sunset announcement](https://opentelemetry.io/blog/2023/sunsetting-opencensus/).\n" + "description": "**Deprecated** as of v1.2.0, may be removed in v2.0.0. The OpenCensus\ncompatibility specification it relies on was deprecated in\nhttps://github.com/open-telemetry/opentelemetry-specification/pull/5138.\nSee also the\n[OpenCensus sunset announcement](https://opentelemetry.io/blog/2023/sunsetting-opencensus/).\n" }
diff --git a/schema/meter_provider.yaml b/schema/meter_provider.yaml index 8b87f2ea..cf01e490 100644 --- a/schema/meter_provider.yaml +++ b/schema/meter_provider.yaml @@ -236,8 +236,8 @@ $defs: description: | Configure metric producer to be opencensus. - **Deprecated** as of June 2026. The OpenCensus compatibility - specification it relies on was deprecated in + **Deprecated** as of v1.2.0, may be removed in v2.0.0. The OpenCensus + compatibility specification it relies on was deprecated in https://github.com/open-telemetry/opentelemetry-specification/pull/5138. SDKs MAY continue to support this entry for backwards compatibility; new configurations SHOULD NOT use it. @@ -250,8 +250,8 @@ $defs: additionalProperties: false deprecated: true description: | - **Deprecated** as of June 2026. The OpenCensus compatibility specification - it relies on was deprecated in + **Deprecated** as of v1.2.0, may be removed in v2.0.0. The OpenCensus + compatibility specification it relies on was deprecated in https://github.com/open-telemetry/opentelemetry-specification/pull/5138. See also the [OpenCensus sunset announcement](https://opentelemetry.io/blog/2023/sunsetting-opencensus/).