Internal change

PiperOrigin-RevId: 972572890

Author: protobuf-github-bot

content/best-practices/1-1-1.md

@@ -8,163 +8,230 @@ aliases = "/programming-guides/1-1-1"
 +++
 
 The "1-1-1" best practice advocates structuring definitions with one top-level
-entity (message, enum, or extension) per `.proto` file, corresponding to a
-single `proto_library` build rule. This approach promotes small, modular proto
-definitions. Key benefits include simplified refactoring, potentially improved
-build times, and smaller binary sizes due to minimized transitive dependencies.
+entry point (exported message, exported enum, service, or extension) per
+`.proto` file, corresponding to a single `proto_library` build rule. This
+approach promotes small, modular proto definitions. Key benefits include
+simplified refactoring, potentially improved build times, and smaller binary
+sizes due to minimized transitive dependencies.
 
-## Rationale
+## Rationale {#rationale}
 
-The 1-1-1 best practice is to keep every proto_library and .proto file as small
-as is reasonable, with the ideal being:
+The 1-1-1 best practice is to keep every `proto_library` and `.proto` file as
+small as is reasonable, with the ideal ratio being:
 
 *   One `proto_library` build rule
 *   One source `.proto` file
-*   One top-level entity (message, enum, or extension)
+*   One top-level entry point (`export message`, `export enum`, `service`, or
+    `extend`)
 
-Having the fewest number of message, enum, extension, and services as you
-reasonably can makes refactoring easier. Moving files when they're separated is
-much easier than extracting messages from a file with other messages.
+Having the fewest number of exported messages, enums, extensions, and services
+as you reasonably can makes refactoring easier. Moving files when they're
+separated is much easier than extracting messages from a file with other
+messages.
 
 Following this practice can help build times and binary size by reducing the
 size of your transitive dependencies in practice: when some code only needs to
-use one enum, under a 1-1-1 design it can depend just on the .proto file that
+use one enum, under a 1-1-1 design it can depend just on the `.proto` file that
 defines that enum and avoid incidentally pulling in a large set of transitive
 dependencies that may only be used by another message defined in the same file.
 
 There are cases where the 1-1-1 ideal is not possible (circular dependencies),
 not ideal (extremely conceptually coupled messages which have readability
 benefits by being co-located), or where some of the downsides don't apply (when
-a .proto file has no imports, then there are no technical concerns about the
+a `.proto` file has no imports, then there are no technical concerns about the
 size of transitive dependencies). As with any best practice, use good judgment
 for when to diverge from the guideline.
 
-One place that modularity of proto schema files is important is when creating
-gRPC
-definitions. The following set of proto files shows modular structure.
+## Symbol Visibility in Edition 2024 and Later {#2024-later}
 
-**student_id.proto**
+Starting in `edition = "2024"`, Protocol Buffers introduces
+[Symbol Visibility](/programming-guides/symbol_visibility)
+with `export` and `local` keywords
+and the `features.default_symbol_visibility` option.
 
-```proto
-edition = "2023";
+> **Scope Note:** Symbol visibility controls **only** the Protobuf compiler
+> (`protoc`) import behavior when resolving references between `.proto` files.
+> It has **no impact** on language-specific generated code or consumers of proto
+> descriptors.
 
-package my.package;
+### Recommended Setting: `STRICT` {#strict}
 
-message StudentId {
-  string value = 1;
-}
+For all new `.proto` files in Edition 2024 and later file-option
+`features.default_symbol_visibility` should be set to STRICT. This is the
+default in edition 2026:
+
+```proto
+option features.default_symbol_visibility = STRICT;
 ```
 
-**full_name.proto**
+In `STRICT` mode:
 
-```proto
-edition = "2023";
+*   All symbols default to `local`.
+*   Only top-level `message` and `enum` declarations intended as entry points
+    may be marked with `export`.
+*   Nested symbols cannot use `export` and are enforced `local` (preventing
+    accidental imports of nested types across file boundaries).
 
-package my.package;
+Top-level messages are designed to be **atomic** with regards to reuse. Nested
+messages and enums are inherently private to their parent container. Attempting
+to use another message's nested types as reusable vocabulary subverts the "use
+all or none" design of `.proto`
+files. Types intended for independent reuse should be
+defined as top-level symbols in dedicated `.proto` files.
 
-message FullName {
-  string family_name = 1;
-  string given_name = 2;
-}
-```
+### Relaxation for `local` Helper Symbols {#relaxation}
 
-**student.proto**
+Symbol visibility relaxes strict 1-1-1 for internal helper symbols: a file may
+contain multiple `local message` or `local enum` definitions, provided they
+support a single top-level entry point (forming a single cluster of `local`
+symbols supporting one entry point). Because `local` symbols cannot be imported
+into other `.proto` files, they do not introduce transitive dependency bloat to
+importers.
+
+### Service Request and Response Messages {#req-res}
+
+Co-locating a `service` and its request/response `message`s in a single file is
+acceptable in Edition 2024 if those request and response messages are marked
+`local` (or default to `local` under `STRICT` mode). This prevents them from
+being imported into other `.proto` files and avoids pulling the `service`
+definition and its gRPC dependencies into unrelated build
+targets.
+
+However, if a request or response message ever needs to be shared or imported
+outside of the service file (for example, for logging, data retention, or reuse
+in another RPC), it should be defined as a top-level `export message` in its own
+dedicated `.proto` file.
+
+## Modular Schema Example {#example}
+
+One place that modularity of proto schema files is important is when
+creating gRPC definitions. The following set of proto
+files shows modular structure in Edition 2024.
+
+**student_id.proto**
 
 ```proto
-edition = "2023";
+edition = "2024";
 
 package my.package;
 
-import "student_id.proto";
-import "full_name.proto";
+option features.default_symbol_visibility = STRICT;
 
-message Student {
-  StudentId id = 1;
-  FullName name = 2;
+export message StudentId {
+  string value = 1;
 }
 ```
 
-**create_student_request.proto**
+**full_name.proto**
 
 ```proto
-edition = "2023";
+edition = "2024";
 
 package my.package;
 
-import "full_name.proto";
+option features.default_symbol_visibility = STRICT;
 
-message CreateStudentRequest {
-  FullName name = 1;
+export message FullName {
+  string family_name = 1;
+  string given_name = 2;
 }
 ```
 
-**create_student_response.proto**
+**student.proto**
 
 ```proto
-edition = "2023";
+edition = "2024";
 
 package my.package;
 
-import "student.proto";
+option features.default_symbol_visibility = STRICT;
 
-message CreateStudentResponse {
-  Student student = 1;
+import "student_id.proto";
+import "full_name.proto";
+
+export message Student {
+  StudentId id = 1;
+  FullName name = 2;
 }
 ```
 
 **get_student_request.proto**
 
 ```proto
-edition = "2023";
+edition = "2024";
 
 package my.package;
 
+option features.default_symbol_visibility = STRICT;
+
 import "student_id.proto";
+import "external/expensive/dependency.proto";
 
-message GetStudentRequest {
+// Export and stand-alone because it is used in both
+// student_request_log.proto AND student_service.proto.
+export message GetStudentRequest {
   StudentId id = 1;
+  expensive.external.OtherMessage message = 2;
 }
 ```
 
-**get_student_response.proto**
+**student_request_log.proto**
 
 ```proto
-edition = "2023";
+edition = "2024";
 
 package my.package;
 
-import "student.proto";
+option features.default_symbol_visibility = STRICT;
 
-message GetStudentResponse {
-  Student student = 1;
+import "get_student_request.proto";
+
+// log any requests made.
+message StudentRequestLog {
+  string requesting_user = 1;
+  GetStudentRequest request = 2;
 }
 ```
 
 **student_service.proto**
 
 ```proto
-edition = "2023";
+edition = "2024";
 
 package my.package;
 
-import "create_student_request.proto";
-import "create_student_response.proto";
+option features.default_symbol_visibility = STRICT;
+
+// imported because we log this message in student_request_log.proto meaning the
+// message needs to be in its own file and `export`.
 import "get_student_request.proto";
-import "get_student_response.proto";
+
+local message GetStudentResponse {
+  Student student = 1;
+}
+
+local message CreateStudentRequest {
+  FullName name = 1;
+}
+
+local message CreateStudentResponse {
+  Student student = 1;
+}
 
 service StudentService {
   rpc CreateStudent(CreateStudentRequest) returns (CreateStudentResponse);
   rpc GetStudent(GetStudentRequest) returns (GetStudentResponse);
 }
 ```
 
-The service definition and each of the message definitions are each in their own
-file, and you use includes to give access to the messages from other schema
-files.
+The service definition and 3 of its 4 message definitions are defined in
+`student_service.proto`. Those messages are all marked `local` making it safe to
+co-locate with the `service` definition without introducing unnecessary
+dependencies. `GetStudentRequest` is shared by the `StudentService` and
+`StudentRequestLog`, and so it should be in its own file.
 
-In this example, `Student`, `StudentId`, and `FullName` are domain types that
-are reusable across requests and responses. The top-level request and response
-protos are unique to each service+method.
+In this example, `Student`, `StudentId`, and `FullName` are public domain types
+that are reusable in logs, requests, responses and external protos.
 
 If you later need to add a `middle_name` field to the `FullName` message, you
 won't need to update every individual top-level message with that new field.

content/best-practices/dos-donts.md

@@ -199,13 +199,28 @@ on the [googleapis repository](https://github.com/googleapis/googleapis).
 
 ## **Do** Define Message Types in Separate Files {#separate-files}
 
-When defining a proto schema, you should have a single message, enum, extension,
-service, or group of cyclic dependencies per file. This makes refactoring
-easier. Moving files when they're separated is much easier than extracting
-messages from a file with other messages. Following this practice also helps to
-keep the proto schema files smaller, which enhances maintainability.
-
-If they will be widely used outside of your project, consider putting them in
+When defining a proto schema, you should have a single top-level entry point
+(exported message, exported enum, service, or extension) per file. This makes
+refactoring easier. Moving files when they're separated is much easier than
+extracting messages from a file with other messages. Following this practice
+also helps to keep the proto schema files smaller, which enhances
+maintainability and reduces transitive dependency bloat.
+
+Symbol visibility (`export` / `local`) relaxes strict separation for internal
+helper types: a `.proto` file may contain multiple `local message` or `local
+enum` definitions supporting a single top-level entry point (such as RPC
+request/response messages supporting a `service`), provided those helper types
+remain local and are not imported into other files.
+
+Messages and enums are intended to be **atomic** with regards to reuse. Nested
+types (messages or enums defined inside another message) are inherently private
+to their parent container. With `STRICT` symbol visibility nested entities
+cannot be exported or imported by other `.proto` files at all. You should not
+use another message's nested types as reusable vocabulary. Any symbol intended
+for independent reuse outside its parent file should be defined as a top-level
+`export message` or `export enum` in its own `.proto` file.
+
+If a type will be widely used outside of your project, consider putting them in
 their own file with no dependencies. Then it's easy for anyone to use those
 types without introducing the transitive dependencies in your other proto files.