open-telemetry · lmolkova · Jul 11, 2026 · Jul 10, 2026 · Jul 10, 2026 · Jul 10, 2026
@@ -113,4 +113,11 @@ New instrumentations must ship a minimal example under the package's `examples/`
 - Versions use the OpenTelemetry beta versioning format `MAJOR.MINORbN` (e.g. `1.0b0`);
   `version.py` carries a `.dev` suffix during development.
 
+## 10. Dependency versioning and compatibility
+
+- Reject dependency changes in `pyproject.toml` that unnecessarily pin versions to exact patch ranges (like `== x.y.z` or `~= x.y.z`).
+- Prefer ranges that allow minor updates (e.g., `~= x.y` or `>= x.y.z, < (x+1)`).
+- For OpenTelemetry-owned beta/pre-release packages (e.g., `opentelemetry-instrumentation`, `opentelemetry-semantic-conventions`, `opentelemetry-util-genai`), enforce the use of `>=` specifiers while pinning the upper boundary to the next major version (e.g., `>= 0.64b0, <1` for `0.x` packages, or `>= 1.0b0, <2` for `1.x` packages) instead of `~=`.
+
+
 See also [AGENTS.md](../../AGENTS.md) for general repo rules.
@@ -11,7 +11,7 @@
     // Default pip_requirements fileMatch only allows [\w-]* between
     // "requirements" and ".txt", so per-instrumentation
     // requirements.latest.txt files are skipped without this.
-    "managerFilePatterns": ["/(^|/)requirements\\.latest\\.txt$/"]
+    "managerFilePatterns": ["/(^|/)requirements\\.txt$/", "/(^|/)requirements\\.latest\\.txt$/"]
   },
   // Manage WEAVER_VERSION and SEMCONV_GENAI_REF in versions.env via their
   // `# renovate:` annotations.

@@ -50,6 +50,14 @@ own `pyproject.toml` and `tests/`. The util package follows the equivalent layou
 - Packages use the OpenTelemetry beta versioning format `MAJOR.MINORbN` (e.g. `1.0b0`). `version.py` carries a `.dev`
   suffix during development (`1.0b0.dev`); the release workflow drops it.
 
+## Dependency versioning and compatibility
+
+- Use compatible release specifiers (e.g., `~= x.y` or `>= x.y.z, < (x+1)`) that pin the major version and allow minor/patch updates.
+- Avoid pinning versions to exact patch ranges (like `== x.y.z` or `~= x.y.z`) in `pyproject.toml` unless strictly necessary.
+- Keep version requirements for shared OpenTelemetry packages (e.g., `opentelemetry-api`, `opentelemetry-instrumentation`, and `opentelemetry-semantic-conventions`) consistent across all packages.
+- For OpenTelemetry-owned beta/pre-release packages (e.g., `opentelemetry-instrumentation`, `opentelemetry-semantic-conventions`, `opentelemetry-util-genai`), use `>=` specifiers and pin the upper boundary to the next major version (e.g., `>= 0.64b0, <1` for `0.x` packages, or `>= 1.0b0, <2` for `1.x` packages) rather than using `~=`.
+
+
 ## Adding a package to the workspace
 
 A new package under `instrumentation/<pkg>/` (where `<pkg>` is the full

@@ -1,5 +1,5 @@
 anthropic>=0.116.0
 opentelemetry-sdk~=1.43.0
-opentelemetry-instrumentation-genai-anthropic
+opentelemetry-instrumentation-genai-anthropic~=1.0b0
 opentelemetry-exporter-otlp-proto-grpc~=1.43.0
 
@@ -1,6 +1,6 @@
 anthropic>=0.116.0
 opentelemetry-sdk~=1.43.0
-opentelemetry-distro~=0.49b2
-opentelemetry-instrumentation-genai-anthropic
+opentelemetry-distro~=0.64b0
+opentelemetry-instrumentation-genai-anthropic~=1.0b0
 opentelemetry-exporter-otlp-proto-grpc~=1.43.0
 
@@ -26,9 +26,9 @@ classifiers = [
 ]
 dependencies = [
   "opentelemetry-api ~= 1.43",
-  "opentelemetry-instrumentation ~= 0.64b0",
-  "opentelemetry-semantic-conventions ~= 0.64b0",
-  "opentelemetry-util-genai >= 1.0b0.dev",
+  "opentelemetry-instrumentation >= 0.64b0, <1",
+  "opentelemetry-semantic-conventions >= 0.64b0, <1",
+  "opentelemetry-util-genai >= 1.0b0, <2",
 ]
 
 [project.optional-dependencies]

@@ -329,8 +329,9 @@ def test_sync_manager_does_not_create_invocation_until_enter():
     factory_calls = []
     wrapper = MessagesStreamManagerWrapper(
         manager=_FakeSyncManager(stream=stream),
-        invocation_factory=lambda: factory_calls.append(True)
-        or _make_invocation(),
+        invocation_factory=lambda: (
+            factory_calls.append(True) or _make_invocation()
+        ),
         capture_content=False,
     )
 

@@ -3,4 +3,4 @@ anyio>=4.14.1
 
 opentelemetry-sdk~=1.43.0
 opentelemetry-exporter-otlp-proto-grpc~=1.43.0
-opentelemetry-instrumentation-genai-claude-agent-sdk
+opentelemetry-instrumentation-genai-claude-agent-sdk~=1.0b0
@@ -3,5 +3,5 @@ anyio>=4.14.1
 
 opentelemetry-sdk~=1.43.0
 opentelemetry-exporter-otlp-proto-grpc~=1.43.0
-opentelemetry-distro~=0.57b0
-opentelemetry-instrumentation-genai-claude-agent-sdk
+opentelemetry-distro~=0.64b0
+opentelemetry-instrumentation-genai-claude-agent-sdk~=1.0b0
@@ -25,9 +25,9 @@ classifiers = [
 ]
 dependencies = [
   "opentelemetry-api ~= 1.43",
-  "opentelemetry-instrumentation ~= 0.64b0",
-  "opentelemetry-semantic-conventions ~= 0.64b0",
-  "opentelemetry-util-genai >= 1.0b0.dev",
+  "opentelemetry-instrumentation >= 0.64b0, <1",
+  "opentelemetry-semantic-conventions >= 0.64b0, <1",
+  "opentelemetry-util-genai >= 1.0b0, <2",
 ]
 
 [project.optional-dependencies]

@@ -2,4 +2,5 @@ langchain>=1.3.12
 langchain-openai>=1.3.4
 langgraph>=1.2.9
 opentelemetry-sdk>=1.43.0
-opentelemetry-exporter-otlp-proto-grpc>=1.43.0
+opentelemetry-exporter-otlp-proto-grpc>=1.43.0
+opentelemetry-instrumentation-genai-langchain~=1.0b0
@@ -5,9 +5,10 @@ description = "Manual instrumentation example for the OpenTelemetry LangChain in
 requires-python = ">=3.10"
 dependencies = [
   "langchain==1.3.12",
-  "langchain-openai>=1.3.3",
+  "langchain-openai>=1.3.4",
   "opentelemetry-sdk>=1.43.0",
   "opentelemetry-exporter-otlp-proto-grpc>=1.43.0",
+  "opentelemetry-instrumentation-genai-langchain~=1.0b0",
 ]
 
 [tool.uv]

@@ -3,5 +3,4 @@ langchain-openai>=1.3.4
 opentelemetry-sdk>=1.43.0
 opentelemetry-exporter-otlp-proto-grpc>=1.43.0
 
-# Uncomment after lanchain instrumetation is released
-# opentelemetry-instrumentation-genai-langchain
+opentelemetry-instrumentation-genai-langchain~=1.0b0
@@ -2,4 +2,5 @@ langchain==1.3.12
 langchain-openai>=1.3.4
 langgraph>=1.2.9
 opentelemetry-sdk>=1.43.0
-opentelemetry-exporter-otlp-proto-grpc>=1.43.0
+opentelemetry-exporter-otlp-proto-grpc>=1.43.0
+opentelemetry-instrumentation-genai-langchain~=1.0b0
@@ -3,3 +3,4 @@ langchain-openai>=1.3.4
 langgraph>=1.2.9
 opentelemetry-sdk>=1.43.0
 opentelemetry-exporter-otlp-proto-grpc>=1.43.0
+opentelemetry-instrumentation-genai-langchain~=1.0b0
@@ -5,10 +5,11 @@ description = "Zero-code instrumentation example for the OpenTelemetry LangChain
 requires-python = ">=3.10"
 dependencies = [
   "langchain==1.3.12",
-  "langchain-openai>=1.3.3",
+  "langchain-openai>=1.3.4",
   "opentelemetry-sdk>=1.43.0",
   "opentelemetry-exporter-otlp-proto-grpc>=1.43.0",
-  "opentelemetry-distro~=0.51b0",
+  "opentelemetry-distro~=0.64b0",
+  "opentelemetry-instrumentation-genai-langchain~=1.0b0",
 ]
 
 [tool.uv]

@@ -2,7 +2,6 @@ langchain==1.3.12
 langchain-openai>=1.3.4
 opentelemetry-sdk>=1.43.0
 opentelemetry-exporter-otlp-proto-grpc>=1.43.0
-opentelemetry-distro~=0.51b0
+opentelemetry-distro~=0.64b0
 
-# Uncomment after lanchain instrumetation is released
-# opentelemetry-instrumentation-genai-langchain
+opentelemetry-instrumentation-genai-langchain~=1.0b0
@@ -25,8 +25,8 @@ classifiers = [
   "Programming Language :: Python :: 3.14",
 ]
 dependencies = [
-  "opentelemetry-instrumentation >= 0.64b0",
-  "opentelemetry-util-genai >= 1.0b0.dev",
+  "opentelemetry-instrumentation >= 0.64b0, <1",
+  "opentelemetry-util-genai >= 1.0b0, <2",
 ]
 
 [project.optional-dependencies]

@@ -3,5 +3,5 @@ python-dotenv>=1.2.2
 
 opentelemetry-sdk~=1.43.0
 opentelemetry-exporter-otlp-proto-grpc~=1.43.0
--e ../../../opentelemetry-instrumentation-genai-openai
--e ../..
+opentelemetry-instrumentation-genai-openai~=1.0b0
+opentelemetry-instrumentation-genai-openai-agents~=1.0b0
@@ -3,5 +3,5 @@ python-dotenv>=1.2.2
 
 opentelemetry-sdk~=1.43.0
 opentelemetry-exporter-otlp-proto-grpc~=1.43.0
-opentelemetry-distro~=0.57b0
-opentelemetry-instrumentation-genai-openai-agents
+opentelemetry-distro~=0.64b0
+opentelemetry-instrumentation-genai-openai-agents~=1.0b0
@@ -25,10 +25,10 @@ classifiers = [
   "Programming Language :: Python :: 3.14",
 ]
 dependencies = [
-  "opentelemetry-api >= 1.43",
-  "opentelemetry-instrumentation >= 0.64b0",
-  "opentelemetry-semantic-conventions >= 0.64b0",
-  "opentelemetry-util-genai >= 1.0b0.dev"
+  "opentelemetry-api ~= 1.43",
+  "opentelemetry-instrumentation >= 0.64b0, <1",
+  "opentelemetry-semantic-conventions >= 0.64b0, <1",
+  "opentelemetry-util-genai >= 1.0b0, <2"
 ]
 
 [project.optional-dependencies]

@@ -2,5 +2,5 @@ openai~=2.44.0
 
 opentelemetry-sdk~=1.43.0
 opentelemetry-exporter-otlp-proto-grpc~=1.43.0
-opentelemetry-distro~=0.57b0
-opentelemetry-instrumentation-genai-openai
+opentelemetry-distro~=0.64b0
+opentelemetry-instrumentation-genai-openai~=1.0b0
@@ -2,7 +2,7 @@ openai~=2.44.0
 
 opentelemetry-sdk~=1.43.0
 opentelemetry-exporter-otlp-proto-grpc~=1.43.0
-opentelemetry-instrumentation-genai-openai
+opentelemetry-instrumentation-genai-openai~=1.0b0
 
 # Uncomment to enable the upload completion hook (pulls in fsspec).
 # Required when OTEL_INSTRUMENTATION_GENAI_COMPLETION_HOOK=upload.

@@ -2,8 +2,8 @@ openai~=2.44.0
 
 opentelemetry-sdk~=1.43.0
 opentelemetry-exporter-otlp-proto-grpc~=1.43.0
-opentelemetry-distro~=0.57b0
-opentelemetry-instrumentation-genai-openai
+opentelemetry-distro~=0.64b0
+opentelemetry-instrumentation-genai-openai~=1.0b0
 
 # Uncomment to enable the upload completion hook (pulls in fsspec).
 # Required when OTEL_INSTRUMENTATION_GENAI_COMPLETION_HOOK=upload.

@@ -26,9 +26,9 @@ classifiers = [
 ]
 dependencies = [
   "opentelemetry-api ~= 1.43",
-  "opentelemetry-instrumentation ~= 0.64b0",
-  "opentelemetry-semantic-conventions ~= 0.64b0",
-  "opentelemetry-util-genai >= 1.0b0.dev",
+  "opentelemetry-instrumentation >= 0.64b0, <1",
+  "opentelemetry-semantic-conventions >= 0.64b0, <1",
+  "opentelemetry-util-genai >= 1.0b0, <2",
 ]
 
 [project.optional-dependencies]

@@ -0,0 +1 @@
+Bump dependencies: opentelemetry-api from ~= 1.30 to ~= 1.43, and opentelemetry-instrumentation and opentelemetry-semantic-conventions from ~= 0.51b0 to >= 0.64b0.
@@ -25,9 +25,9 @@ classifiers = [
   "Programming Language :: Python :: 3.14",
 ]
 dependencies = [
-  "opentelemetry-api ~= 1.30",
-  "opentelemetry-instrumentation ~= 0.51b0",
-  "opentelemetry-semantic-conventions ~= 0.51b0"
+  "opentelemetry-api ~= 1.43",
+  "opentelemetry-instrumentation >= 0.64b0, <1",
+  "opentelemetry-semantic-conventions >= 0.64b0, <1"
 ]
 
 [project.optional-dependencies]

@@ -0,0 +1 @@
+Bump dependencies: opentelemetry-api from ~= 1.40 to ~= 1.43, opentelemetry-instrumentation and opentelemetry-semantic-conventions from >= 0.61b0 to >= 0.64b0, and opentelemetry-util-genai from >= 0.4b0 to >= 1.0b0.
@@ -12,9 +12,9 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-google-genai ~=2.10.0
-opentelemetry-api ~=1.43.0
-opentelemetry-sdk ~=1.43.0
-opentelemetry-exporter-otlp-proto-grpc ~=1.43.0
-opentelemetry-instrumentation-requests ~= 0.51b0
-opentelemetry-instrumentation-google-genai
+google-genai~=2.10.0
+opentelemetry-api~=1.43.0
+opentelemetry-sdk~=1.43.0
+opentelemetry-exporter-otlp-proto-grpc~=1.43.0
+opentelemetry-instrumentation-requests~=0.64b0
+opentelemetry-instrumentation-google-genai~=1.0b0
@@ -12,12 +12,12 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-google-genai ~=2.10.0
-opentelemetry-api ~=1.43.0
-opentelemetry-sdk ~=1.43.0
-opentelemetry-exporter-otlp-proto-grpc ~=1.43.0
-opentelemetry-instrumentation ~= 0.51b0
-opentelemetry-instrumentation-requests ~= 0.51b0
-opentelemetry-instrumentation-google-genai
-opentelemetry-contrib-instrumentations ~= 0.51b0
-opentelemetry-distro[otlp] ~= 0.51b0
+google-genai~=2.10.0
+opentelemetry-api~=1.43.0
+opentelemetry-sdk~=1.43.0
+opentelemetry-exporter-otlp-proto-grpc~=1.43.0
+opentelemetry-instrumentation~=0.64b0
+opentelemetry-instrumentation-requests~=0.64b0
+opentelemetry-instrumentation-google-genai~=1.0b0
+opentelemetry-contrib-instrumentations~=0.64b0
+opentelemetry-distro[otlp]~=0.64b0
@@ -39,9 +39,9 @@ classifiers = [
   "Programming Language :: Python :: 3.14",
 ]
 dependencies = [
-  "opentelemetry-api ~=1.40",
-  "opentelemetry-instrumentation >=0.61b0, <2",
-  "opentelemetry-semantic-conventions >=0.61b0, <2",
+  "opentelemetry-api ~= 1.43",
+  "opentelemetry-instrumentation >= 0.64b0, <1",
+  "opentelemetry-semantic-conventions >= 0.64b0, <1",
   "opentelemetry-util-genai >= 1.0b0, <2",
   "wrapt >= 1.0.0, < 3.0.0",
 ]

@@ -25,8 +25,8 @@ classifiers = [
   "Programming Language :: Python :: 3.14",
 ]
 dependencies = [
-  "opentelemetry-instrumentation ~= 0.64b0",
-  "opentelemetry-semantic-conventions ~= 0.64b0",
+  "opentelemetry-instrumentation >= 0.64b0, <1",
+  "opentelemetry-semantic-conventions >= 0.64b0, <1",
   "opentelemetry-api ~= 1.43",
   "wrapt >= 1.0.0, < 3.0.0",
 ]
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		Bump dependencies: opentelemetry-api from ~= 1.30 to ~= 1.43, and opentelemetry-instrumentation and opentelemetry-semantic-conventions from ~= 0.51b0 to >= 0.64b0.