From 490f882e6242daf769a94fc55162de3cd9f14e77 Mon Sep 17 00:00:00 2001 From: zurex Date: Wed, 11 Dec 2024 23:15:10 +0800 Subject: [PATCH] [DOC] Update existing maintaining dependencies doc (#3195) --- docs/maintaining-dependencies.md | 397 +++++++++++++++++-------------- 1 file changed, 217 insertions(+), 180 deletions(-) diff --git a/docs/maintaining-dependencies.md b/docs/maintaining-dependencies.md index 31a50db521..f213e653ca 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,8 @@ 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 +88,8 @@ 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,47 +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. -#### 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) For bazel, two different methods to build exists. @@ -599,3 +430,209 @@ abcd1234abcd1234abcd1234abcd1234abcd1234abcd1234abcd1234abcd1234 v1.2.4.tar.gz ``` Update the `sha256`. + +## Upgrade a git submodule + +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. + +### 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 can see 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 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 + +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 + +> Remember, 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") +```