Skip to content

Make environment variable propagation operational guidance non-normative#5165

Open
pellared wants to merge 8 commits into
open-telemetry:mainfrom
pellared:env-car-operational-doc
Open

Make environment variable propagation operational guidance non-normative#5165
pellared wants to merge 8 commits into
open-telemetry:mainfrom
pellared:env-car-operational-doc

Conversation

@pellared

@pellared pellared commented Jun 18, 2026

Copy link
Copy Markdown
Member

Motivation

The Environment Variables as Context Propagation Carriers specification used normative wording in the "Operational Guidance" section for application-level usage advice, such as when applications read environment variables or how they prepare child process environments.

That made the section read like it was adding specification requirements for application behavior, even though the intent is guidance for how environment variable carriers are typically used.

This came up in discussion with @dashpole and also I mentioned this in open-telemetry/opentelemetry-go-contrib#9112 (comment)

Here is a simple example how the languages can be document some operational guidance: open-telemetry/opentelemetry-go-contrib@5b1606f

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This PR updates the Environment Variables as Context Propagation Carriers specification to ensure the “Operational Guidance” section reads as non-normative application guidance rather than introducing new normative requirements.

Changes:

  • Reword “Operational Guidance” recommendations to avoid normative RFC 2119 keywords for application behavior.
  • Clarify process-startup immutability and child-process environment handling guidance.
  • Add a changelog entry documenting the clarification.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.

File Description
specification/context/env-carriers.md Rewords the Operational Guidance section to be non-normative guidance and adjusts phrasing around immutability, process spawning, and security.
CHANGELOG.md Adds an Unreleased changelog entry noting the operational guidance is non-normative and should be documented by language implementations.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Comment thread specification/context/env-carriers.md Outdated
Comment thread specification/context/env-carriers.md Outdated
Comment thread specification/context/env-carriers.md Outdated
pellared and others added 2 commits June 18, 2026 15:46
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
@pellared pellared marked this pull request as ready for review June 18, 2026 13:47
@pellared pellared requested a review from a team as a code owner June 18, 2026 13:47
Context-related environment variables are best treated as process-startup input:

- Applications SHOULD read context-related environment variables during
- Applications should read context-related environment variables during

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Instead of just lower casing these terms, can you use a synonym (e.g. ought to, are advised to, need to, are expected to). This avoids the confusion of readers thinking these were normative statements that have syntax errors.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this would be even more clear a6cbb14

@pellared pellared requested a review from MrAlias June 18, 2026 19:09

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

Comment thread specification/context/env-carriers.md
Comment thread specification/context/env-carriers.md Outdated
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants