From 70323a45879607df19057c313d58d37ddf126f00 Mon Sep 17 00:00:00 2001 From: Evan Zhu Date: Thu, 5 Dec 2024 23:50:33 +0800 Subject: [PATCH 1/5] Add common pattern and remove similar part --- docs/maintaining-dependencies.md | 389 +++++++++++++++++-------------- 1 file changed, 210 insertions(+), 179 deletions(-) diff --git a/docs/maintaining-dependencies.md b/docs/maintaining-dependencies.md index 31a50db521..6a33e7efc6 100644 --- a/docs/maintaining-dependencies.md +++ b/docs/maintaining-dependencies.md @@ -14,6 +14,13 @@ Also, another good place to start when upgrading something to N+1 is to find the commit that upgraded to version N (use `git blame`), and inspect the commit for the last upgrade. +## Overview + +| Dependency | Type | +| -------------------- | ------------- | +| opentelemetry-proto | git submodule | +| prometheus-cpp | git submodule | + ## opentelemetry-proto ### Comments (opentelemetry-proto) @@ -49,71 +56,7 @@ In this example, we upgrade from 1.3.1 to 1.3.2 #### directory third_party/opentelemetry-proto -This is a `git submodule`, it needs to point to the new tag. - -```shell -cd third_party/opentelemetry-proto -git log -1 -``` - -The current submodule show something like: - -```shell -commit b3060d2104df364136d75a35779e6bd48bac449a (HEAD, tag: v1.3.1) -Author: Damien Mathieu <42@dmathieu.com> -Date: Thu Apr 25 17:55:35 2024 +0200 - - generate profiles proto for CI (#552) -``` - -Pull new tags: - -```shell -git pull --tag origin -``` - -Upgrade to a new tag: - -```shell -git pull origin v1.3.2 -``` - -Check the new state: - -```shell -git log -1 -``` - -```shell -commit 40b3c1b746767cbc13c2e39da3eaf1a23e54ffdd (HEAD, tag: v1.3.2) -Author: jack-berg <34418638+jack-berg@users.noreply.github.com> -Date: Fri Jun 28 08:19:11 2024 -0500 - - Prepare changelog for 1.3.2 release (#563) - - Co-authored-by: Armin Ruech <7052238+arminru@users.noreply.github.com> -``` - -Go back to the root of opentelemetry-cpp - -```shell -cd ../.. -git status -``` - -```shell -On branch upgrade_proto_1.3.2 -Changes not staged for commit: - (use "git add ..." to update what will be committed) - (use "git restore ..." to discard changes in working directory) - modified: third_party/opentelemetry-proto (new commits) -``` - -Add the upgraded submodule: - -```shell -git add third_party/opentelemetry-proto -``` +You need to update the git submodule third_party/opentelemetry-proto, check [Upgrade a git submodule](#upgrade-a-git-submodule) for more details. #### file third_party_release @@ -144,80 +87,7 @@ index 0bbf67f3..7362473f 100644 #### file bazel/repository.bzl -Locate the entry for opentelemetry-proto: - -```text - # OTLP Protocol definition - maybe( - http_archive, - name = "com_github_opentelemetry_proto", - build_file = "@io_opentelemetry_cpp//bazel:opentelemetry_proto.BUILD", - sha256 = "bed250ceec8e4a83aa5604d7d5595a61945059dc662edd058a9da082283f7a00", - strip_prefix = "opentelemetry-proto-1.3.1", - urls = [ - "https://github.com/open-telemetry/opentelemetry-proto/archive/v1.3.1.tar.gz", - ], - ) -``` - -Update the URL to the new tag: - -```text - urls = [ - "https://github.com/open-telemetry/opentelemetry-proto/archive/v1.3.2.tar.gz", - ], -``` - -Update strip_prefix to the new tag: - -```text - strip_prefix = "opentelemetry-proto-1.3.2", -``` - -Download the new URL: - -```shell -wget https://github.com/open-telemetry/opentelemetry-proto/archive/v1.3.2.tar.gz -``` - -Run a checksum on the new file: - -```shell -sha256sum v1.3.2.tar.gz -``` - -```shell -c069c0d96137cf005d34411fa67dd3b6f1f8c64af1e7fb2fe0089a41c425acd7 v1.3.2.tar.gz -``` - -Update the checksum in file bazel/repository.bzl: - -```text - sha256 = "c069c0d96137cf005d34411fa67dd3b6f1f8c64af1e7fb2fe0089a41c425acd7", -``` - -Typical change: - -```shell -[malff@malff-desktop opentelemetry-cpp]$ git diff bazel/repository.bzl -diff --git a/bazel/repository.bzl b/bazel/repository.bzl -index bac1e45b..508b95a3 100644 ---- a/bazel/repository.bzl -+++ b/bazel/repository.bzl -@@ -88,10 +88,10 @@ def opentelemetry_cpp_deps(): - http_archive, - name = "com_github_opentelemetry_proto", - build_file = "@io_opentelemetry_cpp//bazel:opentelemetry_proto.BUILD", -- sha256 = "bed250ceec8e4a83aa5604d7d5595a61945059dc662edd058a9da082283f7a00", -- strip_prefix = "opentelemetry-proto-1.3.1", -+ sha256 = "c069c0d96137cf005d34411fa67dd3b6f1f8c64af1e7fb2fe0089a41c425acd7", -+ strip_prefix = "opentelemetry-proto-1.3.2", - urls = [ -- "https://github.com/open-telemetry/opentelemetry-proto/archive/v1.3.1.tar.gz", -+ "https://github.com/open-telemetry/opentelemetry-proto/archive/v1.3.2.tar.gz", - ], - ) -``` +Please follow the guide [Upgrade a bazel dependency](#upgrade-a-bazel-dependency) for more details. #### file cmake/opentelemetry-proto.cmake @@ -269,46 +139,6 @@ In this case, it is better to: When the C++ code requires a newer minimum version of opentelemetry-proto, make sure to document this, including in the release notes. -#### file MODULE.bazel - -Make sure the new tag is available in bazel central: - -* [bazel-central](https://registry.bazel.build/modules/opentelemetry-proto) - -If missing, file a PR to add it, or contact the maintainer: - -* [repository](https://github.com/bazelbuild/bazel-central-registry/tree/main/modules/opentelemetry-proto) - -Update the opentelemetry-proto version to the new tag: - -```text -bazel_dep(name = "opentelemetry-proto", version = "1.3.2", repo_name = "com_github_opentelemetry_proto") -``` - -File `MODULE.bazel` is used in the github CI for repository -opentelemetry-cpp, so using a tag that does not exist (yet) in bazel central -will break the CI build. - -See the known issues section. - -Typical change: - -```shell -[malff@malff-desktop opentelemetry-cpp]$ git diff MODULE.bazel -diff --git a/MODULE.bazel b/MODULE.bazel -index 7b84c2b7..3161ffb1 100644 ---- a/MODULE.bazel -+++ b/MODULE.bazel -@@ -13,7 +13,7 @@ bazel_dep(name = "bazel_skylib", version = "1.5.0") - bazel_dep(name = "curl", version = "8.4.0") - bazel_dep(name = "grpc", version = "1.62.1", repo_name = "com_github_grpc_grpc") - bazel_dep(name = "nlohmann_json", version = "3.11.3", repo_name = "github_nlohmann_json") --bazel_dep(name = "opentelemetry-proto", version = "1.3.1", repo_name = "com_github_opentelemetry_proto") -+bazel_dep(name = "opentelemetry-proto", version = "1.3.2", repo_name = "com_github_opentelemetry_proto") - bazel_dep(name = "opentracing-cpp", version = "1.6.0", repo_name = "com_github_opentracing") - bazel_dep(name = "platforms", version = "0.0.8") - bazel_dep(name = "prometheus-cpp", version = "1.2.4", repo_name = "com_github_jupp0r_prometheus_cpp") -``` ### Known issues (opentelemetry-proto) @@ -599,3 +429,204 @@ abcd1234abcd1234abcd1234abcd1234abcd1234abcd1234abcd1234abcd1234 v1.2.4.tar.gz ``` Update the `sha256`. + +## Upgrade a git submodule +All the git submodule is under the folder `third_party`. We will use `opentelemetry-propto` as example in this case. This is a `git submodule`, it needs to point to the new tag. + +### Get current tag + +```shell +cd third_party/opentelemetry-proto +git log -1 +``` + +The current submodule show something like: + +```shell +commit b3060d2104df364136d75a35779e6bd48bac449a (HEAD, tag: v1.3.1) +Author: Damien Mathieu <42@dmathieu.com> +Date: Thu Apr 25 17:55:35 2024 +0200 + + generate profiles proto for CI (#552) +``` + +In this case we could know the current tag is `v.1.3.1`. + +### Upgrade to new tag + +Pull new tags: + +```shell +git pull --tag origin +``` + +Upgrade to a new tag: + +```shell +git pull origin v1.3.2 +``` + +Check the new state: + +```shell +git log -1 +``` + +```shell +commit 40b3c1b746767cbc13c2e39da3eaf1a23e54ffdd (HEAD, tag: v1.3.2) +Author: jack-berg <34418638+jack-berg@users.noreply.github.com> +Date: Fri Jun 28 08:19:11 2024 -0500 + + Prepare changelog for 1.3.2 release (#563) + + Co-authored-by: Armin Ruech <7052238+arminru@users.noreply.github.com> +``` + +### Add changes + +Go back to the root of opentelemetry-cpp + +```shell +cd ../.. +git status +``` + +```shell +On branch upgrade_proto_1.3.2 +Changes not staged for commit: + (use "git add ..." to update what will be committed) + (use "git restore ..." to discard changes in working directory) + modified: third_party/opentelemetry-proto (new commits) +``` + +Add the upgraded submodule: + +```shell +git add third_party/opentelemetry-proto +``` + +## Upgrade a bazel dependency + +Same as git submodule, we will continue use `opentelemetry-proto` as example. + +All the bazel dependencies is defined in [repository.bzl](../bazel/repository.bzl) and [MODULE.bazel](../MODULE.bazel). + +### Update the dependency in repository.bzl + +Locate the entry for opentelemetry-proto: + +```text + # OTLP Protocol definition + maybe( + http_archive, + name = "com_github_opentelemetry_proto", + build_file = "@io_opentelemetry_cpp//bazel:opentelemetry_proto.BUILD", + sha256 = "bed250ceec8e4a83aa5604d7d5595a61945059dc662edd058a9da082283f7a00", + strip_prefix = "opentelemetry-proto-1.3.1", + urls = [ + "https://github.com/open-telemetry/opentelemetry-proto/archive/v1.3.1.tar.gz", + ], + ) +``` + +Update the URL to the new tag: + +```text + urls = [ + "https://github.com/open-telemetry/opentelemetry-proto/archive/v1.3.2.tar.gz", + ], +``` + +Update strip_prefix to the new tag: + +```text + strip_prefix = "opentelemetry-proto-1.3.2", +``` + +Download the new URL: + +```shell +wget https://github.com/open-telemetry/opentelemetry-proto/archive/v1.3.2.tar.gz +``` + +Run a checksum on the new file: + +```shell +sha256sum v1.3.2.tar.gz +``` + +```shell +c069c0d96137cf005d34411fa67dd3b6f1f8c64af1e7fb2fe0089a41c425acd7 v1.3.2.tar.gz +``` + +Update the checksum in file bazel/repository.bzl: + +```text + sha256 = "c069c0d96137cf005d34411fa67dd3b6f1f8c64af1e7fb2fe0089a41c425acd7", +``` + +Typical change: + +```shell +[malff@malff-desktop opentelemetry-cpp]$ git diff bazel/repository.bzl +diff --git a/bazel/repository.bzl b/bazel/repository.bzl +index bac1e45b..508b95a3 100644 +--- a/bazel/repository.bzl ++++ b/bazel/repository.bzl +@@ -88,10 +88,10 @@ def opentelemetry_cpp_deps(): + http_archive, + name = "com_github_opentelemetry_proto", + build_file = "@io_opentelemetry_cpp//bazel:opentelemetry_proto.BUILD", +- sha256 = "bed250ceec8e4a83aa5604d7d5595a61945059dc662edd058a9da082283f7a00", +- strip_prefix = "opentelemetry-proto-1.3.1", ++ sha256 = "c069c0d96137cf005d34411fa67dd3b6f1f8c64af1e7fb2fe0089a41c425acd7", ++ strip_prefix = "opentelemetry-proto-1.3.2", + urls = [ +- "https://github.com/open-telemetry/opentelemetry-proto/archive/v1.3.1.tar.gz", ++ "https://github.com/open-telemetry/opentelemetry-proto/archive/v1.3.2.tar.gz", + ], + ) +``` + +#### Update MODULE.bazel + +> Remeber, the link is different in your case. Replace `opentelemetry-proto` to correct target. + +Make sure the new tag is available in bazel central: + +* opentelemetry-proto bazel-central: https://registry.bazel.build/modules/opentelemetry-proto + +If missing, file a PR to add it, or contact the maintainer: + +* opentelemetry-proto repository: https://github.com/bazelbuild/bazel-central-registry/tree/main/modules/opentelemetry-proto + +Update the `opentelemetry-proto` version to the new tag: + +```text +bazel_dep(name = "opentelemetry-proto", version = "1.3.2", repo_name = "com_github_opentelemetry_proto") +``` + +File `MODULE.bazel` is used in the github CI for repository +opentelemetry-cpp, so using a tag that does not exist (yet) in bazel central +will break the CI build. + +See the known issues section. + +Typical change: + +```shell +[malff@malff-desktop opentelemetry-cpp]$ git diff MODULE.bazel +diff --git a/MODULE.bazel b/MODULE.bazel +index 7b84c2b7..3161ffb1 100644 +--- a/MODULE.bazel ++++ b/MODULE.bazel +@@ -13,7 +13,7 @@ bazel_dep(name = "bazel_skylib", version = "1.5.0") + bazel_dep(name = "curl", version = "8.4.0") + bazel_dep(name = "grpc", version = "1.62.1", repo_name = "com_github_grpc_grpc") + bazel_dep(name = "nlohmann_json", version = "3.11.3", repo_name = "github_nlohmann_json") +-bazel_dep(name = "opentelemetry-proto", version = "1.3.1", repo_name = "com_github_opentelemetry_proto") ++bazel_dep(name = "opentelemetry-proto", version = "1.3.2", repo_name = "com_github_opentelemetry_proto") + bazel_dep(name = "opentracing-cpp", version = "1.6.0", repo_name = "com_github_opentracing") + bazel_dep(name = "platforms", version = "0.0.8") + bazel_dep(name = "prometheus-cpp", version = "1.2.4", repo_name = "com_github_jupp0r_prometheus_cpp") +``` From 3aac4cf5ff2e21cb3023b77bf92f9df958bb817e Mon Sep 17 00:00:00 2001 From: Evan Zhu Date: Wed, 11 Dec 2024 19:26:59 +0800 Subject: [PATCH 2/5] format doc to meet the requirement --- docs/maintaining-dependencies.md | 22 ++++++++++++++-------- 1 file changed, 14 insertions(+), 8 deletions(-) diff --git a/docs/maintaining-dependencies.md b/docs/maintaining-dependencies.md index 6a33e7efc6..55941ad5dc 100644 --- a/docs/maintaining-dependencies.md +++ b/docs/maintaining-dependencies.md @@ -56,7 +56,8 @@ In this example, we upgrade from 1.3.1 to 1.3.2 #### directory third_party/opentelemetry-proto -You need to update the git submodule third_party/opentelemetry-proto, check [Upgrade a git submodule](#upgrade-a-git-submodule) for more details. +You need to update the git submodule third_party/opentelemetry-proto, +check [Upgrade a git submodule](#upgrade-a-git-submodule) for more details. #### file third_party_release @@ -87,7 +88,8 @@ index 0bbf67f3..7362473f 100644 #### file bazel/repository.bzl -Please follow the guide [Upgrade a bazel dependency](#upgrade-a-bazel-dependency) for more details. +Please follow the guide [Upgrade a bazel dependency](#upgrade-a-bazel-dependency) +for more details. #### file cmake/opentelemetry-proto.cmake @@ -139,7 +141,6 @@ In this case, it is better to: When the C++ code requires a newer minimum version of opentelemetry-proto, make sure to document this, including in the release notes. - ### Known issues (opentelemetry-proto) For bazel, two different methods to build exists. @@ -431,7 +432,10 @@ abcd1234abcd1234abcd1234abcd1234abcd1234abcd1234abcd1234abcd1234 v1.2.4.tar.gz Update the `sha256`. ## Upgrade a git submodule -All the git submodule is under the folder `third_party`. We will use `opentelemetry-propto` as example in this case. This is a `git submodule`, it needs to point to the new tag. + +All the git submodule is under the folder `third_party`. +We will use `opentelemetry-propto` as example in this case. +This is a `git submodule`, it needs to point to the new tag. ### Get current tag @@ -509,7 +513,8 @@ git add third_party/opentelemetry-proto Same as git submodule, we will continue use `opentelemetry-proto` as example. -All the bazel dependencies is defined in [repository.bzl](../bazel/repository.bzl) and [MODULE.bazel](../MODULE.bazel). +All the bazel dependencies is defined in [repository.bzl](../bazel/repository.bzl) +and [MODULE.bazel](../MODULE.bazel). ### Update the dependency in repository.bzl @@ -590,15 +595,16 @@ index bac1e45b..508b95a3 100644 #### Update MODULE.bazel -> Remeber, the link is different in your case. Replace `opentelemetry-proto` to correct target. +> Remeber, the link is different in your case. +Replace `opentelemetry-proto` to correct target. Make sure the new tag is available in bazel central: -* opentelemetry-proto bazel-central: https://registry.bazel.build/modules/opentelemetry-proto +* [opentelemetry-proto bazel-central](https://registry.bazel.build/modules/opentelemetry-proto) If missing, file a PR to add it, or contact the maintainer: -* opentelemetry-proto repository: https://github.com/bazelbuild/bazel-central-registry/tree/main/modules/opentelemetry-proto +* [opentelemetry-proto repository](https://github.com/bazelbuild/bazel-central-registry/tree/main/modules/opentelemetry-proto) Update the `opentelemetry-proto` version to the new tag: From e464d64bd2e0bb20f2da42a7f0bb93540d4397c0 Mon Sep 17 00:00:00 2001 From: Evan Zhu Date: Wed, 11 Dec 2024 20:58:16 +0800 Subject: [PATCH 3/5] Fix typo and use absolute link path --- docs/maintaining-dependencies.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/maintaining-dependencies.md b/docs/maintaining-dependencies.md index 55941ad5dc..ef859c11a7 100644 --- a/docs/maintaining-dependencies.md +++ b/docs/maintaining-dependencies.md @@ -513,8 +513,8 @@ git add third_party/opentelemetry-proto Same as git submodule, we will continue use `opentelemetry-proto` as example. -All the bazel dependencies is defined in [repository.bzl](../bazel/repository.bzl) -and [MODULE.bazel](../MODULE.bazel). +All the bazel dependencies is defined in [repository.bzl](https://github.com/open-telemetry/opentelemetry-cpp/blob/main/bazel/repository.bzl) +and [MODULE.bazel](https://github.com/open-telemetry/opentelemetry-cpp/blob/main/MODULE.bazel). ### Update the dependency in repository.bzl @@ -595,7 +595,7 @@ index bac1e45b..508b95a3 100644 #### Update MODULE.bazel -> Remeber, the link is different in your case. +> Remember, the link is different in your case. Replace `opentelemetry-proto` to correct target. Make sure the new tag is available in bazel central: From ad9d38d0c7e49817ea4228b8ebd08bdd2bc949ff Mon Sep 17 00:00:00 2001 From: Marc Alff Date: Wed, 11 Dec 2024 14:40:10 +0100 Subject: [PATCH 4/5] Apply suggestions from code review --- docs/maintaining-dependencies.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/maintaining-dependencies.md b/docs/maintaining-dependencies.md index ef859c11a7..f213e653ca 100644 --- a/docs/maintaining-dependencies.md +++ b/docs/maintaining-dependencies.md @@ -433,7 +433,7 @@ Update the `sha256`. ## Upgrade a git submodule -All the git submodule is under the folder `third_party`. +All the git submodule are under the folder `third_party`. We will use `opentelemetry-propto` as example in this case. This is a `git submodule`, it needs to point to the new tag. @@ -454,7 +454,7 @@ Date: Thu Apr 25 17:55:35 2024 +0200 generate profiles proto for CI (#552) ``` -In this case we could know the current tag is `v.1.3.1`. +In this case we can see the current tag is `v.1.3.1`. ### Upgrade to new tag @@ -513,7 +513,7 @@ git add third_party/opentelemetry-proto Same as git submodule, we will continue use `opentelemetry-proto` as example. -All the bazel dependencies is defined in [repository.bzl](https://github.com/open-telemetry/opentelemetry-cpp/blob/main/bazel/repository.bzl) +All the bazel dependencies are defined in [repository.bzl](https://github.com/open-telemetry/opentelemetry-cpp/blob/main/bazel/repository.bzl) and [MODULE.bazel](https://github.com/open-telemetry/opentelemetry-cpp/blob/main/MODULE.bazel). ### Update the dependency in repository.bzl From 716dcf9ffe3b78820328105c681a931da3e4c04b Mon Sep 17 00:00:00 2001 From: Evan Zhu Date: Wed, 11 Dec 2024 21:41:38 +0800 Subject: [PATCH 5/5] Fix according to the review comments --- docs/maintaining-dependencies.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/maintaining-dependencies.md b/docs/maintaining-dependencies.md index ef859c11a7..f213e653ca 100644 --- a/docs/maintaining-dependencies.md +++ b/docs/maintaining-dependencies.md @@ -433,7 +433,7 @@ Update the `sha256`. ## Upgrade a git submodule -All the git submodule is under the folder `third_party`. +All the git submodule are under the folder `third_party`. We will use `opentelemetry-propto` as example in this case. This is a `git submodule`, it needs to point to the new tag. @@ -454,7 +454,7 @@ Date: Thu Apr 25 17:55:35 2024 +0200 generate profiles proto for CI (#552) ``` -In this case we could know the current tag is `v.1.3.1`. +In this case we can see the current tag is `v.1.3.1`. ### Upgrade to new tag @@ -513,7 +513,7 @@ git add third_party/opentelemetry-proto Same as git submodule, we will continue use `opentelemetry-proto` as example. -All the bazel dependencies is defined in [repository.bzl](https://github.com/open-telemetry/opentelemetry-cpp/blob/main/bazel/repository.bzl) +All the bazel dependencies are defined in [repository.bzl](https://github.com/open-telemetry/opentelemetry-cpp/blob/main/bazel/repository.bzl) and [MODULE.bazel](https://github.com/open-telemetry/opentelemetry-cpp/blob/main/MODULE.bazel). ### Update the dependency in repository.bzl