Make environment variable propagation operational guidance non-normative#5165
Make environment variable propagation operational guidance non-normative#5165pellared wants to merge 8 commits into
Conversation
There was a problem hiding this comment.
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.
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
| 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 |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
I think this would be even more clear a6cbb14
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
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