Pin protobuf related dependencies (#309)

We can't use wide dependencies because otherwise when building the
wheel, the latest version is used, but the generate code should use the
minimum supported version for the generation, not the latest one. See:
https://protobuf.dev/support/cross-version-runtime-guarantee/.

For doing this we also need to depend on `frequence-api-common` v0.6.2+
because it is the version that contains the same fix for the generated
files.

We also take the opportunity to remove the `google-common-protos`
dependency from the API projects by default and to bump the `grpcio`
dependency to `1.66.1` and to fix an issue with `mkdocstrings` and newer
`griffe` versions.

Author: llucax

RELEASE_NOTES.md

@@ -19,6 +19,9 @@
 ### Cookiecutter template
 
 * Group GitHub Actions dependabot updates.
+* API projects don't include the `google-common-protos` dependency by default.
+* API projects updated the `grpcio` dependency to `1.66.1`.
+* API projects updated the `frequenz-api-common` dependency to `0.6`.
 
 ## Bug Fixes
 

cookiecutter/{{cookiecutter.github_repo_name}}/.gitmodules

@@ -1,7 +1,4 @@
 {% if cookiecutter.type == "api" -%}
-[submodule "submodules/api-common-protos"]
-	path = submodules/api-common-protos
-	url = https://github.com/googleapis/api-common-protos.git
 [submodule "submodules/frequenz-api-common"]
 	path = submodules/frequenz-api-common
 	url = https://github.com/frequenz-floss/frequenz-api-common.git

cookiecutter/{{cookiecutter.github_repo_name}}/mkdocs.yml

@@ -124,7 +124,7 @@ plugins:
             - https://frequenz-floss.github.io/frequenz-channels-python/v0.16/objects.inv
             - https://frequenz-floss.github.io/frequenz-sdk-python/v0.25/objects.inv
 {%- elif cookiecutter.type == "api" %}
-            - https://frequenz-floss.github.io/frequenz-api-common/v0.3/objects.inv
+            - https://frequenz-floss.github.io/frequenz-api-common/v0.6/objects.inv
             - https://grpc.github.io/grpc/python/objects.inv
 {%- endif %}
             - https://typing-extensions.readthedocs.io/en/stable/objects.inv

cookiecutter/{{cookiecutter.github_repo_name}}/pyproject.toml

@@ -6,6 +6,15 @@ requires = [
   "setuptools == 70.1.1",
   "setuptools_scm[toml] == 8.1.0",
   "frequenz-repo-config[{{cookiecutter.type}}] == 0.10.0",
+{%- if cookiecutter.type == "api" %}
+  # We need to pin the protobuf, grpcio and  grpcio-tools dependencies to make
+  # sure the code is generated using the minimum supported versions, as older
+  # versions can't work with code that was generated with newer versions.
+  # https://protobuf.dev/support/cross-version-runtime-guarantee/#backwards
+  "protobuf == 5.28.0",
+  "grpcio-tools == 1.66.1",
+  "grpcio == 1.66.1",
+{%- endif %}
 ]
 build-backend = "setuptools.build_meta"
 
@@ -43,9 +52,15 @@ dependencies = [
 ]
 {%- elif cookiecutter.type == "api" %}
 dependencies = [
-  "frequenz-api-common >= 0.5.0, < 0.6.0",
-  "googleapis-common-protos >= 1.56.2, < 2",
-  "grpcio >= 1.51.1, < 2",
+  "frequenz-api-common >= 0.6.2, < 0.7.0",
+  # We can't widen beyond the current value unless we bump the minimum
+  # requirements too because of protobuf cross-version runtime guarantees:
+  # https://protobuf.dev/support/cross-version-runtime-guarantee/#major
+  "protobuf >= 5.28.0, < 7", # Do not widen beyond 7!
+  # We couldn't find any document with a spec about the cross-version runtime
+  # guarantee for grpcio, so unless we find one in the future, we'll assume
+  # major version jumps are not compatible
+  "grpcio >= 1.66.1, < 2", # Do not widen beyond 2!
 ]
 {%- else %}
 dependencies = [
@@ -76,8 +91,8 @@ dev-mkdocs = [
   "mkdocs-literate-nav == 0.6.1",
   "mkdocs-macros-plugin == 1.0.5",
   "mkdocs-material == 9.5.27",
-  "mkdocstrings[python] == 0.25.1",
-  "mkdocstrings-python == 1.10.5",
+  "mkdocstrings[python] == 0.26.1",
+  "mkdocstrings-python == 1.11.1",
   "frequenz-repo-config[{{cookiecutter.type}}] == 0.10.0",
 ]
 dev-mypy = [

pyproject.toml

@@ -82,8 +82,8 @@ dev-mkdocs = [
   "mkdocs-literate-nav == 0.6.1",
   "mkdocs-macros-plugin == 1.0.5",
   "mkdocs-material == 9.5.30",
-  "mkdocstrings[python] == 0.25.2",
-  "mkdocstrings-python == 1.10.7",
+  "mkdocstrings[python] == 0.26.1",
+  "mkdocstrings-python == 1.11.1",
 ]
 dev-mypy = [
   "mypy == 1.11.1",

src/frequenz/repo/config/__init__.py

@@ -340,8 +340,8 @@
 # Glob pattern to use to find the proto files in the proto_path (default: "*.proto")
 proto_glob = "*.prt"  # Default: "*.proto"
 # List of paths to pass to the protoc compiler as include paths (default:
-# ["submodules/api-common-protos", "submodules/frequenz-api-common/proto"])
-include_paths = ["submodules/api-common-protos"]
+# ["submodules/frequenz-api-common/proto"])
+include_paths = ["submodules/frequenz-api-common/proto"]
 # Path where to generate the Python files (default: "py")
 py_path = "generated"
 # Path where to generate the documentation files (default: "protobuf-reference")
@@ -376,23 +376,18 @@
 section plus the following:
 
 - `pytests/`: Directory containing the tests for the Python code.
-- `submodules/api-common-protos`: Directory containing the Git submodule with the
-  `google/api-common-protos` repository.
 - `submodules/frequenz-api-common`: Directory containing the Git submodule with the
   `frequenz-floss/frequenz-api-common` repository.
 
 Normally Frequenz APIs use basic types from
-[`google/api-common-protos`](https://github.com/googleapis/api-common-protos) and
 [`frequenz-floss/frequenz-api-common`](https://github.com/frequenz-floss/frequenz-api-common),
 so you need to make sure the proper submodules are added to your project:
 
 ```sh
 mkdir submodules
-git submodule add https://github.com/googleapis/api-common-protos.git \
-        submodules/api-common-protos
 git submodule add https://github.com/frequenz-floss/frequenz-api-common.git \
         submodules/frequenz-api-common
-git commit -m "Add api-common-protos and frequenz-api-common submodules" submodules
+git commit -m "Add frequenz-api-common submodule" submodules
 ```
 
 Then you need to add this package as a build dependency and a few extra
@@ -435,13 +430,11 @@
 ```
 
 Finally you need to make sure to include the generated `*.pyi` files in the
-source distribution, as well as the Google api-common-protos files, as it
-is not handled automatically yet
+source distribution, as it is not handled automatically yet
 ([#13](https://github.com/frequenz-floss/frequenz-repo-config-python/issues/13)).
 Make sure to include these lines in the `MANIFEST.in` file:
 
 ```
-recursive-include submodules/api-common-protos/google *.proto
 recursive-include submodules/frequenz-api-common/proto *.proto
 ```
 

src/frequenz/repo/config/protobuf.py

@@ -27,10 +27,7 @@ class ProtobufConfig:
     proto_glob: str = "*.proto"
     """The glob pattern to use to find the protobuf files."""
 
-    include_paths: Sequence[str] = (
-        "submodules/api-common-protos",
-        "submodules/frequenz-api-common/proto",
-    )
+    include_paths: Sequence[str] = ("submodules/frequenz-api-common/proto",)
     """The paths to add to the include path when compiling the protobuf files."""
 
     py_path: str = "py"

tests_golden/integration/test_cookiecutter_generation/actor/frequenz-actor-test/pyproject.toml

@@ -58,8 +58,8 @@ dev-mkdocs = [
   "mkdocs-literate-nav == 0.6.1",
   "mkdocs-macros-plugin == 1.0.5",
   "mkdocs-material == 9.5.27",
-  "mkdocstrings[python] == 0.25.1",
-  "mkdocstrings-python == 1.10.5",
+  "mkdocstrings[python] == 0.26.1",
+  "mkdocstrings-python == 1.11.1",
   "frequenz-repo-config[actor] == 0.10.0",
 ]
 dev-mypy = [

tests_golden/integration/test_cookiecutter_generation/api/frequenz-api-test/.gitmodules

@@ -1,6 +1,3 @@
-[submodule "submodules/api-common-protos"]
-	path = submodules/api-common-protos
-	url = https://github.com/googleapis/api-common-protos.git
 [submodule "submodules/frequenz-api-common"]
 	path = submodules/frequenz-api-common
 	url = https://github.com/frequenz-floss/frequenz-api-common.git

tests_golden/integration/test_cookiecutter_generation/api/frequenz-api-test/mkdocs.yml

@@ -120,7 +120,7 @@ plugins:
             # TODO(cookiecutter): You might want to add other external references here
             # See https://mkdocstrings.github.io/python/usage/#import for details
             - https://docs.python.org/3/objects.inv
-            - https://frequenz-floss.github.io/frequenz-api-common/v0.3/objects.inv
+            - https://frequenz-floss.github.io/frequenz-api-common/v0.6/objects.inv
             - https://grpc.github.io/grpc/python/objects.inv
             - https://typing-extensions.readthedocs.io/en/stable/objects.inv
   # Note this plugin must be loaded after mkdocstrings to be able to use macros