feat: stabilize semantic conventions package

.changelog/5698.added

@@ -0,0 +1 @@
+`opentelemetry-semantic-conventions`: stabilize semantic conventions package

eachdist.ini

@@ -26,6 +26,7 @@ packages=
     opentelemetry-exporter-otlp-proto-http
     opentelemetry-exporter-otlp
     opentelemetry-api
+    opentelemetry-semantic-conventions
 
 [prerelease]
 version=0.67b0.dev
@@ -42,7 +43,6 @@ packages=
     opentelemetry-exporter-otlp-common
     opentelemetry-configuration
     opentelemetry-proto-json
-    opentelemetry-semantic-conventions
     opentelemetry-test-utils
 
 [lintroots]

opentelemetry-sdk/pyproject.toml

@@ -27,7 +27,7 @@ classifiers = [
 ]
 dependencies = [
   "opentelemetry-api == 1.46.0.dev",
-  "opentelemetry-semantic-conventions == 0.67b0.dev",
+  "opentelemetry-semantic-conventions == 1.46.0.dev",
   "typing-extensions >= 4.5.0",
 ]
 

opentelemetry-semantic-conventions/DEVELOPMENT.md

@@ -0,0 +1,26 @@
+# OpenTelemetry Semantic Conventions
+
+The modules in this package are generated from the
+[OpenTelemetry Semantic Conventions](https://github.com/open-telemetry/semantic-conventions)
+registry using [weaver](https://github.com/open-telemetry/weaver). Do **NOT** modify the
+generated files by hand.
+
+## Updating to a new semantic conventions release
+
+1. In `scripts/semconv/generate.sh`, set `SEMCONV_VERSION` to the new release
+   (and bump `OTEL_WEAVER_IMG_VERSION` if needed).
+2. Add the new schema URL to `Schemas` in
+   `src/opentelemetry/semconv/schemas.py`. The script fails if it is missing.
+3. Run `scripts/semconv/generate.sh` (requires Docker).
+4. **Update the "Supported Semantic Conventions Version" section of
+   [`README.rst`](README.rst) to the new `SEMCONV_VERSION`**, including the
+   link to the upstream tag. The README must always state the semantic
+   conventions version this package is generated from.
+5. Review the diff against the compatibility rules below, then commit.
+
+## Compatibility rules
+
+This package is on the stable 1.x release line. The stable modules
+(`opentelemetry.semconv.attributes`, `opentelemetry.semconv.metrics` and
+`opentelemetry.semconv.schemas`) are public API and **MUST** stay backwards
+compatible.

opentelemetry-semantic-conventions/README.rst

@@ -6,7 +6,7 @@ OpenTelemetry Semantic Conventions
 .. |pypi| image:: https://badge.fury.io/py/opentelemetry-semantic-conventions.svg
    :target: https://pypi.org/project/opentelemetry-semantic-conventions/
 
-This library contains generated code for the semantic conventions defined by the OpenTelemetry specification.
+This library contains generated code for the `OpenTelemetry Semantic Conventions`_.
 
 Installation
 ------------
@@ -15,23 +15,101 @@ Installation
 
     pip install opentelemetry-semantic-conventions
 
-Code Generation
----------------
+Supported Semantic Conventions Version
+--------------------------------------
 
-These files were generated automatically from code in semconv_.
-To regenerate the code, run ``../scripts/semconv/generate.sh``.
+This release of the package is generated from
+`OpenTelemetry Semantic Conventions v1.44.0 <https://github.com/open-telemetry/semantic-conventions/tree/v1.44.0>`_.
 
-To build against a new release or specific commit of opentelemetry-specification_,
-update the ``SPEC_VERSION`` variable in
-``../scripts/semconv/generate.sh``. Then run the script and commit the changes.
+The version of this package is independent of the semantic conventions version it
+is generated from. Check this section, or ``opentelemetry.semconv.schemas.Schemas``,
+to find out which semantic conventions version a given release supports.
 
-.. _opentelemetry-specification: https://github.com/open-telemetry/opentelemetry-specification
-.. _semconv: https://github.com/open-telemetry/opentelemetry-python/tree/main/scripts/semconv
+Stability
+---------
 
+This package follows `Semantic Versioning <https://semver.org/>`_ for its
+**public** modules only (i.e. portions of the semantic conventions which have
+been marked as **stable**).
+
+Stable modules
+~~~~~~~~~~~~~~
+
+The following modules contain only conventions marked **stable** upstream:
+
+* ``opentelemetry.semconv.attributes.*``
+* ``opentelemetry.semconv.metrics.*``
+* ``opentelemetry.semconv.schemas``
+
+Within the 1.x release line, these modules will not remove or rename any symbol.
+Upgrading can still change them in the following ways:
+
+* New attributes, metrics, enum members and schema URLs may be added in minor releases.
+* An attribute or metric may be **deprecated** when the semantic conventions deprecate it.
+  Deprecated symbols are documented as deprecated (enum classes are also marked with
+  ``@deprecated``), but remain available.
+* Documentation (docstrings) may change.
+
+Incubating modules
+~~~~~~~~~~~~~~~~~~
+
+.. warning::
+
+   Anything under ``opentelemetry.semconv._incubating`` is **not** covered by
+   Semantic Versioning and is subject to breaking changes across **minor** (and patch)
+   versions of this package.
+
+``opentelemetry.semconv._incubating.attributes.*`` and
+``opentelemetry.semconv._incubating.metrics.*`` contain every convention in the
+semantic conventions registry, including those in development or experimental/deprecated
+ones. These can be renamed, changed or removed upstream at any time
+and this package will follow those changes without a major version bump.
+
+.. important::
+
+   Libraries that depend on anything under ``opentelemetry.semconv._incubating``
+   **SHOULD** pin an exact version of this package, for example::
+
+       dependencies = [
+           "opentelemetry-semantic-conventions == 1.46.0",
+       ]
+
+   A version range such as ``~= 1.46`` or ``>= 1.46`` can break your library when a
+   new minor version of this package is released.
+
+The ``_incubating`` modules also contain copies of the stable conventions, marked as
+deprecated in favor of the stable module. When a convention is available in a stable
+module, import it from there.
+
+Library authors that wish to depend on incubating semantic conventions without having
+to pin `opentelemetry-semantic-conventions` can consider vendoring incubating conventions
+directly into their package.
+
+Other caveats
+~~~~~~~~~~~~~
+
+* Not every semantic conventions namespace is generated. Namespaces specific to other
+  languages or runtimes (e.g. ``jvm``, ``dotnet``, ``go`` and ``nodejs``) are
+  excluded. See ``excluded_namespaces`` in the
+  `weaver configuration <https://github.com/open-telemetry/opentelemetry-python/blob/main/scripts/semconv/templates/registry/weaver.yaml>`_.
+  Excluded namespaces may be added in a future minor release.
+* ``opentelemetry.semconv.trace`` and ``opentelemetry.semconv.resource`` are legacy
+  modules and are deprecated. Use ``opentelemetry.semconv.attributes`` or
+  ``opentelemetry.semconv._incubating.attributes`` instead.
+
+Contributing
+------------
+
+This package is generated. See `DEVELOPMENT.md`_ for how to regenerate it and
+the compatibility rules maintainers must follow.
 
 References
 ----------
 
 * `OpenTelemetry Project <https://opentelemetry.io/>`_
-* `OpenTelemetry Semantic Conventions Definitions <https://github.com/open-telemetry/semantic-conventions/blob/main/docs/README.md>`_
-* `generate.sh script <https://github.com/open-telemetry/opentelemetry-python/blob/main/scripts/semconv/generate.sh>`_
+* `OpenTelemetry Semantic Conventions`_
+* `Semantic Conventions repository <https://github.com/open-telemetry/semantic-conventions>`_
+* `Semantic Conventions stability guarantees <https://opentelemetry.io/docs/specs/otel/versioning-and-stability/#semantic-conventions-stability>`_
+
+.. _OpenTelemetry Semantic Conventions: https://opentelemetry.io/docs/specs/semconv/
+.. _DEVELOPMENT.md: https://github.com/open-telemetry/opentelemetry-python/blob/main/opentelemetry-semantic-conventions/DEVELOPMENT.md

opentelemetry-semantic-conventions/src/opentelemetry/semconv/version/__init__.py

@@ -1,4 +1,4 @@
 # Copyright The OpenTelemetry Authors
 # SPDX-License-Identifier: Apache-2.0
 
-__version__ = "0.67b0.dev"
+__version__ = "1.46.0.dev"