From 98166c68b7fa35003a998a01e7a1234537654788 Mon Sep 17 00:00:00 2001 From: emdneto <9735060+emdneto@users.noreply.github.com> Date: Tue, 10 Dec 2024 21:44:37 -0300 Subject: [PATCH 1/8] contributing: add guidance for update package versions support Signed-off-by: emdneto <9735060+emdneto@users.noreply.github.com> --- CONTRIBUTING.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e90402edc2..8e659fbcae 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -278,6 +278,19 @@ Below is a checklist of things to be mindful of when implementing a new instrume - Testing - When adding a new instrumentation remember to update `tox.ini` adding appropriate rules in `envlist`, `command_pre` and `commands` sections +### Update supported instrumentation package versions + +- Update the respective instrumentation `pyproject.toml` file in _instruments_ entry under `[project.optional-dependencies]` section +- Update instrumentation `package.py` file in `_instruments` variable +- Run command `tox -e generate` to regenerate necessary files + +If you're adding support for a new version of the instrumentation package, follow these additional steps: + +- Add new test-requirements.txt file with the respective package version required for testing +- Add a new test environment entry for the package version in `tox.ini` and run `tox -e generate-workflows` to generate new workflows + +Example PRs: [#2976](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/2976), [#2845](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/2845) + ## Guideline for GenAI instrumentations Instrumentations that relate to [Generative AI](https://opentelemetry.io/docs/specs/semconv/gen-ai/) systems will be placed in the [instrumentation-genai](./instrumentation-genai) folder. This section covers contributions related to those instrumentations. Please note that the [guidelines for instrumentations](#guideline-for-instrumentations) and [expectations from contributors](#expectations-from-contributors) still apply. From 02550adb1f4f7f5e9909ae68e53fca1b0b1da055 Mon Sep 17 00:00:00 2001 From: emdneto <9735060+emdneto@users.noreply.github.com> Date: Wed, 11 Dec 2024 09:20:31 -0300 Subject: [PATCH 2/8] update the guide Signed-off-by: emdneto <9735060+emdneto@users.noreply.github.com> --- CONTRIBUTING.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8e659fbcae..e51963bbe9 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -280,14 +280,15 @@ Below is a checklist of things to be mindful of when implementing a new instrume ### Update supported instrumentation package versions -- Update the respective instrumentation `pyproject.toml` file in _instruments_ entry under `[project.optional-dependencies]` section -- Update instrumentation `package.py` file in `_instruments` variable -- Run command `tox -e generate` to regenerate necessary files +- Navigate to the **instrumentation package directory:** + - Update the respective instrumentation **`pyproject.toml`** file by modifying _instruments_ entry in the [project.optional-dependencies] section with the new version constraint + - Update instrumentation **`package.py`** file in `_instruments` variable with the new version constraint +- At the **root of the project directory**, run `tox -e generate` to regenerate necessary files If you're adding support for a new version of the instrumentation package, follow these additional steps: -- Add new test-requirements.txt file with the respective package version required for testing -- Add a new test environment entry for the package version in `tox.ini` and run `tox -e generate-workflows` to generate new workflows +- At the **instrumentation package directory:** Add new test-requirements.txt file with the respective package version required for testing +- At the **root of the project directory**: Add a new test environment entry for the package version in [tox.ini](./tox.ini) and run `tox -e generate-workflows` to regenerate new workflows accordingly. At the same file, search for `opentelemetry-instrumentation-{package}/test-requirements` and add a new line to point to the new test-requirements.txt you created in the previous step so tox can install the correct requirements. Example PRs: [#2976](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/2976), [#2845](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/2845) From 067196615b1a9165fdca27dfd87c42d6e279d65d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Em=C3=ADdio=20Neto?= <9735060+emdneto@users.noreply.github.com> Date: Wed, 11 Dec 2024 09:24:11 -0300 Subject: [PATCH 3/8] Update CONTRIBUTING.md --- CONTRIBUTING.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e51963bbe9..614a552345 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -281,14 +281,14 @@ Below is a checklist of things to be mindful of when implementing a new instrume ### Update supported instrumentation package versions - Navigate to the **instrumentation package directory:** - - Update the respective instrumentation **`pyproject.toml`** file by modifying _instruments_ entry in the [project.optional-dependencies] section with the new version constraint + - Update the respective instrumentation **`pyproject.toml`** file by modifying _instruments_ entry in the `[project.optional-dependencies]` section with the new version constraint - Update instrumentation **`package.py`** file in `_instruments` variable with the new version constraint - At the **root of the project directory**, run `tox -e generate` to regenerate necessary files If you're adding support for a new version of the instrumentation package, follow these additional steps: - At the **instrumentation package directory:** Add new test-requirements.txt file with the respective package version required for testing -- At the **root of the project directory**: Add a new test environment entry for the package version in [tox.ini](./tox.ini) and run `tox -e generate-workflows` to regenerate new workflows accordingly. At the same file, search for `opentelemetry-instrumentation-{package}/test-requirements` and add a new line to point to the new test-requirements.txt you created in the previous step so tox can install the correct requirements. +- At the **root of the project directory**: Add a new test environment entry for the package version in [tox.ini](./tox.ini) and run `tox -e generate-workflows` to regenerate new workflows accordingly. In the same [tox.ini](./tox.ini) file, search for `opentelemetry-instrumentation-{package}/test-requirements` and add a new line to point to the new test-requirements.txt you created in the previous step so tox can install the correct requirements. Example PRs: [#2976](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/2976), [#2845](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/2845) From 91db843f9c5b2f23e89b1ef4ba0218f5538e61c9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Em=C3=ADdio=20Neto?= <9735060+emdneto@users.noreply.github.com> Date: Wed, 11 Dec 2024 11:14:49 -0300 Subject: [PATCH 4/8] Update CONTRIBUTING.md Co-authored-by: Riccardo Magliocchetti --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 614a552345..1b46132257 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -281,7 +281,7 @@ Below is a checklist of things to be mindful of when implementing a new instrume ### Update supported instrumentation package versions - Navigate to the **instrumentation package directory:** - - Update the respective instrumentation **`pyproject.toml`** file by modifying _instruments_ entry in the `[project.optional-dependencies]` section with the new version constraint + - Update **`pyproject.toml`** file by modifying _instruments_ entry in the `[project.optional-dependencies]` section with the new version constraint - Update instrumentation **`package.py`** file in `_instruments` variable with the new version constraint - At the **root of the project directory**, run `tox -e generate` to regenerate necessary files From abb7a319835f0cb876000552041834f3cade389b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Em=C3=ADdio=20Neto?= <9735060+emdneto@users.noreply.github.com> Date: Wed, 11 Dec 2024 11:14:56 -0300 Subject: [PATCH 5/8] Update CONTRIBUTING.md Co-authored-by: Riccardo Magliocchetti --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1b46132257..e0424473dc 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -282,7 +282,7 @@ Below is a checklist of things to be mindful of when implementing a new instrume - Navigate to the **instrumentation package directory:** - Update **`pyproject.toml`** file by modifying _instruments_ entry in the `[project.optional-dependencies]` section with the new version constraint - - Update instrumentation **`package.py`** file in `_instruments` variable with the new version constraint + - Update `_instruments` variable in instrumentation **`package.py`** file with the new version constraint - At the **root of the project directory**, run `tox -e generate` to regenerate necessary files If you're adding support for a new version of the instrumentation package, follow these additional steps: From 371070973ce62732ea99217bceb5c4550b5e35ab Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Em=C3=ADdio=20Neto?= <9735060+emdneto@users.noreply.github.com> Date: Thu, 12 Dec 2024 11:00:52 -0300 Subject: [PATCH 6/8] Update CONTRIBUTING.md to add docs instructions --- CONTRIBUTING.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e0424473dc..c807f0f74c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -63,7 +63,7 @@ You can run `tox` with the following arguments: * `tox` to run all existing tox commands, including unit tests for all packages under multiple Python versions -* `tox -e docs` to regenerate the API docs +* `tox -e docs` to regenerate all docs * `tox -e py312-test-instrumentation-aiopg` to e.g. run the aiopg instrumentation unit tests under a specific Python version * `tox -e spellcheck` to run a spellcheck on all the code @@ -89,7 +89,9 @@ for more detail on available tox commands. ### Troubleshooting -> Some packages may require additional system wide dependencies to be installed. For example, you may need to install `libpq-dev` to run the postgresql client libraries instrumentation tests. or `libsnappy-dev` to run the prometheus exporter tests. If you encounter a build error, please check the installation instructions for the package you are trying to run tests for. +Some packages may require additional system-wide dependencies to be installed. For example, you may need to install `libpq-dev` to run the postgresql client libraries instrumentation tests or `libsnappy-dev` to run the prometheus exporter tests. If you encounter a build error, please check the installation instructions for the package you are trying to run tests for. + +For `docs` building, you may need to install `mysql-client` and other required dependencies as necessary. Ensure the Python version used in your local setup matches the version used in the CI to maintain compatibility when building the documentation. ### Benchmarks From ff6f523214440cd958591cbe53f4eabe77f0fceb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Em=C3=ADdio=20Neto?= <9735060+emdneto@users.noreply.github.com> Date: Thu, 12 Dec 2024 11:05:14 -0300 Subject: [PATCH 7/8] Update CONTRIBUTING.md --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c807f0f74c..780703ade6 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -63,7 +63,7 @@ You can run `tox` with the following arguments: * `tox` to run all existing tox commands, including unit tests for all packages under multiple Python versions -* `tox -e docs` to regenerate all docs +* `tox -e docs` to regenerate all docs * `tox -e py312-test-instrumentation-aiopg` to e.g. run the aiopg instrumentation unit tests under a specific Python version * `tox -e spellcheck` to run a spellcheck on all the code From bdd88f6f89bb5153ddc9496de28c0bf1076b78a1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Em=C3=ADdio=20Neto?= <9735060+emdneto@users.noreply.github.com> Date: Tue, 17 Dec 2024 15:04:10 -0300 Subject: [PATCH 8/8] Update CONTRIBUTING.md --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 780703ade6..ab22d3821f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -91,7 +91,7 @@ for more detail on available tox commands. Some packages may require additional system-wide dependencies to be installed. For example, you may need to install `libpq-dev` to run the postgresql client libraries instrumentation tests or `libsnappy-dev` to run the prometheus exporter tests. If you encounter a build error, please check the installation instructions for the package you are trying to run tests for. -For `docs` building, you may need to install `mysql-client` and other required dependencies as necessary. Ensure the Python version used in your local setup matches the version used in the CI to maintain compatibility when building the documentation. +For `docs` building, you may need to install `mysql-client` and other required dependencies as necessary. Ensure the Python version used in your local setup matches the version used in the [CI](./.github/workflows/) to maintain compatibility when building the documentation. ### Benchmarks