This documentation change includes the following:

* Removes some internal-only content from the public version of `/best-practices/api.md`
* Redirects links to content moved to the `/best-practices` directory
* Adds `features.utf8_validation` to the code sample in the Editions overview topic
* Adds a section about error handling in Go Opaque API

PiperOrigin-RevId: 714026940
Change-Id: Ie852bbfe813dba8cddd96ee6897b8252ea992421

Author: Protocol Buffer Team

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

@@ -4,6 +4,7 @@ weight = 105
 linkTitle = "1-1-1 Best Practice"
 description = "All proto definitions should have one top-level element and build target per file."
 type = "docs"
+aliases = "/programming-guides/1-1-1"
 +++
 
 The 1-1-1 best practice is to keep every proto_library and .proto file as small

content/best-practices/api.md

@@ -3,13 +3,14 @@ title = "API Best Practices"
 weight = 100
 description = "A future-proof API is surprisingly hard to get right. The suggestions in this document make trade-offs to favor long-term, bug-free evolution."
 type = "docs"
+aliases = "/programming-guides/api"
 +++
 
 Updated for proto3. Patches welcome!
 
 This doc is a complement to
-[Proto Best Practices](/programming-guides/dos-donts).
-It's not a prescription for Java/C++/Go and other APIs.
+[Proto Best Practices](/best-practices/dos-donts). It's
+not a prescription for Java/C++/Go and other APIs.
 
 If you see a proto straying from these guidelines in a code review, point the
 author to this topic and help spread the word.
@@ -730,31 +731,6 @@ your service name, even if it is defined inside a specific package. For example,
 a service named `Watcher` is likely to cause problems; something like
 `MyProjectWatcher` would be better.
 
-## Ensure Every RPC Specifies and Enforces a (Permissive) Deadline {#every-rpc-deadline}
-
-By default, an RPC does not have a timeout. Since a request may tie up backend
-resources that are only released on completion, setting a default deadline that
-allows all well-behaving requests to finish is a good defensive practice. Not
-enforcing one has in the past caused
-severe problems for major services . RPC clients
-should still set a deadline on outgoing RPCs and will typically do so by default
-when they use standard frameworks. A deadline may and typically will be
-overwritten by a shorter deadline attached to a request.
-
-Setting the `deadline` option clearly communicates the RPC
-deadline to your clients, and is respected and enforced by standard frameworks:
-
-```proto
-rpc Foo(FooRequest) returns (FooResponse) {
-  option deadline = x; // there is no globally good default
-}
-```
-
-Choosing a deadline value will especially impact how your system acts under
-load. For existing services, it is critical to evaluate existing client behavior
-before enforcing new deadlines to avoid breaking clients (consult SRE). In some
-cases, it may not be possible to enforce a shorter deadline after the fact.
-
 ## Bound Request and Response Sizes {#bound-req-res-sizes}
 
 Request and response sizes should be bounded.

content/best-practices/dos-donts.md

@@ -3,6 +3,7 @@ title = "Proto Best Practices"
 weight = 90
 description = "Shares vetted best practices for authoring Protocol Buffers."
 type = "docs"
+aliases = "/programming-guides/dos-donts"
 +++
 
 Clients and servers are never updated at exactly the same time - even when you

content/editions/overview.md

@@ -127,6 +127,8 @@ edition = "2023";
 
 package com.example;
 
+option features.utf8_validation = NONE;
+
 message Player {
   // fields have explicit presence, so no explicit setting needed
   string name = 1 [default = "N/A"];

content/overview.md

@@ -279,7 +279,7 @@ Protocol buffers support many scalar value types, including integers that use
 both variable-length encoding and fixed sizes. You can also create your own
 composite data types by defining messages that are, themselves, data types that
 you can assign to a field. In addition to the simple and composite value types,
-several [common types](/programming-guides/dos-donts#common)
+several [common types](/best-practices/dos-donts#common)
 are published.
 
 ## History {#history}

content/programming-guides/editions.md

@@ -977,8 +977,8 @@ to store your protocol buffer messages, the changes that you can make in your
 proto definition are different. {{% /alert %}}
 
 Check
-[Proto Best Practices](/programming-guides/dos-donts) and
-the following rules:
+[Proto Best Practices](/best-practices/dos-donts) and the
+following rules:
 
 *   Don't change the field numbers for any existing fields. "Changing" the field
     number is equivalent to deleting the field and adding a new field with the

content/programming-guides/proto2.md

@@ -1025,8 +1025,8 @@ to store your protocol buffer messages, the changes that you can make in your
 proto definition are different. {{% /alert %}}
 
 Check
-[Proto Best Practices](/programming-guides/dos-donts) and
-the following rules:
+[Proto Best Practices](/best-practices/dos-donts) and the
+following rules:
 
 *   Don't change the field numbers for any existing fields. "Changing" the field
     number is equivalent to deleting the field and adding a new field with the

content/programming-guides/proto3.md

@@ -978,8 +978,8 @@ to store your protocol buffer messages, the changes that you can make in your
 proto definition are different. {{% /alert %}}
 
 Check
-[Proto Best Practices](/programming-guides/dos-donts) and
-the following rules:
+[Proto Best Practices](/best-practices/dos-donts) and the
+following rules:
 
 *   Don't change the field numbers for any existing fields. "Changing" the field
     number is equivalent to deleting the field and adding a new field with the

content/programming-guides/serialization-not-canonical.md

@@ -7,7 +7,7 @@ type = "docs"
 
 <!--*
 # Document freshness: For more information, see go/fresh-source.
-freshness: { owner: 'haberman' reviewed: '2024-02-05' }
+freshness: { owner: 'esrauch' reviewed: '2025-01-09' }
 *-->
 
 Many people want a serialized proto to canonically represent the contents of

content/reference/go/opaque-faq.md

@@ -90,6 +90,13 @@ you need to migrate said file to editions first.
 1.  Run your unit and integration tests, and then roll out to a staging
     environment.
 
+## Are Errors Ignored with Lazy Decoding? {#lazydecodingerrors}
+
+No.
+[`proto.Marshal`](https://pkg.go.dev/google.golang.org/protobuf/proto?tab=doc#Marshal)
+will always validate the wire format data, even when decoding is deferred until
+first access.
+
 ## Where Can I Ask Questions or Report Issues? {#questions}
 
 If you found an issue with the `open2opaque` migration tool (such as incorrectly

content/reference/rust/rust-redaction.md

@@ -16,7 +16,7 @@ Use the standard `fmt::Debug` ("`{:?}`" in format strings) on Protobuf messages
 for human-readable strings for logging, error messages, exceptions, and similar
 use cases. The output of this debug info is not intended to be machine-readable
 (unlike `TextFormat` and `JSON` which are
-[not be used for debug output](/programming-guides/dos-donts#text-format-interchange)).
+[not be used for debug output](/best-practices/dos-donts#text-format-interchange)).
 
 Using `fmt::Debug` enables redaction of some sensitive fields.