Announce proto_h changes

PiperOrigin-RevId: 859363574

Author: mkruskal-google

content/news/2026-01-20.md

@@ -0,0 +1,125 @@
++++
+title = "Changes Announced on January 20, 2026"
+linkTitle = "January 20, 2026"
+toc_hide = "true"
+description = "Changes announced for Protocol Buffers on January 20, 2026."
+type = "docs"
++++
+
+## Efficient headers in C++
+
+As of the 34.0 release, the C++ code generator will start setting the `proto_h`
+option by default. Instead of just producing a `pb.h` header, it will begin
+producing both `pb.h` and `proto.h` ones. This provides a more efficient option
+to reduce build times in systems with large proto trees.
+
+### Opting out
+
+When `proto_h` is set, `pb.h` headers will still be generated for convenience
+when build size isn't a concern. You can continue to use these as before, as
+long as you make sure the `proto.h` headers are provided in your include path.
+The `pb.h` files will now simply import the `proto.h` header and all of their
+dependencies' `pb.h` files instead of defining any symbols themselves.
+
+If you hit problems with getting `proto.h` on your include path, you can restore
+the old behavior by passing the generator argument `proto_h=false` to protoc.
+For example:
+
+```
+protoc --cpp_opt=proto_h=false --cpp_out=out/dir myproto.proto
+```
+
+### Why `proto.h`?
+
+The traditional `pb.h` file transitively includes all the `pb.h` files of every
+other `.proto` whose messages are referenced in the file. As some of our message
+types reference hundreds of different message types, this can result in any code
+using a single field from one of these messages paying to compile the headers
+from every one of its referenced messages. This causes heavy load on your builds
+due to excessively long compiles, and even break them due to the amount of code
+being built.
+
+By contrast, `proto.h` headers do not include the headers for all the file's
+referenced messages. Instead, they use forward declarations to minimize the APIs
+exposed, which dramatically reduces compile time for some message types.
+
+### Using `proto.h`
+
+Because `proto.h` files don't include other message types' headers, you may need
+to modify your `#include`s in order to use them. For example, let's say you have
+two `.proto` files, `foo.proto` and `bar.proto`:
+
+```proto
+// my_package/foo.proto
+edition = "2023";
+
+package my_package;
+
+message Foo {
+  int32 some_data = 42;
+}
+
+enum Truthy {
+  TRUTHY_UNSPECIFIED = 0;
+  TRUTHY_FALSE = 1;
+  TRUTHY_TRUE = 2;
+  TRUTHY_MAYBE = 3;
+}
+```
+
+```proto
+// my_package/bar.proto
+edition = "2023";
+
+import "my_package/foo.proto";
+
+package my_package;
+
+message Bar {
+  Truthy some_flag = 42;
+  repeated Foo foo = 43;
+}
+```
+
+Using `pb.h` headers, you can write code like this:
+
+```c++
+// my_package/test1.cc
+#include "my_package/bar.pb.h"
+namespace my_package {
+void Test1Function1(const Bar &bar_message) {
+  if (bar_message.some_flag()) { ... }
+}
+void Test1Function2(const Bar &bar_message) {
+  if (bar_message.some_flag() != MAYBE) { ... }
+}
+void Test1Function3(const Bar &bar_message) {
+  for (Foo foo : bar_message.foos()) {
+    DoSomething(foo.some_data());
+  }
+  ...
+}
+```
+
+However, this will **not** work with `proto.h`, because you won't have the
+header information for `foo.proto`. To get this code to work, you need to
+`#include` the `proto.h` headers for both `bar.proto` **and** `foo.proto`.
+
+```c++
+// my_package/test1.cc
+#include "my_package/bar.proto.h"
+#include "my_package/foo.proto.h"
+namespace my_package {
+void Test1Function1(const Bar &bar_message) {
+  if (bar_message.some_flag()) { ... }
+}
+void Test1Function2(const Bar &bar_message) {
+  if (bar_message.some_flag() != MAYBE) { ... }
+}
+void Test1Function3(const Bar &bar_message) {
+  for (Foo foo : bar_message.foos()) {
+    DoSomething(foo.some_data());
+  }
+  ...
+}
+```

content/news/_index.md

@@ -20,6 +20,8 @@ New news topics will also be published to the
 The following news topics provide information in the reverse order in which it
 was released.
 
+*   [January 20, 2026](/news/2026-01-20) - Efficient
+    headers in C++
 *   [January 16, 2026](/news/2026-01-16) - Prebuilt proto
     compiler (protoc) for Bazel
 *   [September 19, 2025](/news/2025-09-19) - Breaking