Merge pull request #229 from Logofile/sync

Documentation change

Author: tonyliaoss

content/_index.md

@@ -24,10 +24,12 @@ Objective-C, Python, and Ruby. With proto3, you can also work with PHP.
 ## Example Implementation
 
 ```proto
+edition = "2023";
+
 message Person {
-  optional string name = 1;
-  optional int32 id = 2;
-  optional string email = 3;
+  string name = 1;
+  int32 id = 2;
+  string email = 3;
 }
 ```
 

content/best-practices/no-cargo-cults.md

@@ -0,0 +1,22 @@
++++
+title = "Avoid Cargo Culting"
+weight = 90
+description = "Avoid using features where they are not needed."
+type = "docs"
++++
+
+Do not [cargo cult](http://go/cargocult-definition) settings in proto files. If
+you are creating a new proto file based on existing schema definitions, don't
+apply option settings except for those that you understand the need for.
+
+## Best Practices Specific to Editions {#editions}
+
+Avoid applying [editions features](/editions/features)
+except when they're actually necessary. Features in `.proto` files signal the
+use of either experimental future behaviors or deprecated past behaviors. Best
+practices for the latest edition will always be the default. New proto schema
+definition content should remain feature-free, except if you want to early-adopt
+a feature for future behavior that's being rolled out.
+
+Copying-forward feature settings without understanding why they are set can lead
+to unexpected behaviors in your code.

content/editions/features.md

@@ -9,6 +9,11 @@ This topic provides an overview of the features that are included in Edition
 2023. Each subsequent edition's features will be added to this topic. We
 announce new editions in [the News section](/news).
 
+Before configuring feature settings in your new schema definition content, make
+sure you understand why you are using them. Avoid
+[cargo-culting](/best-practices/no-cargo-cults) with
+features.
+
 ## Prototiller {#prototiller}
 
 Prototiller is a command-line tool that converts proto2 and proto3 definition

content/overview.md

@@ -31,10 +31,12 @@ data on disk. Protocol buffer *messages* and *services* are described by
 engineer-authored `.proto` files. The following shows an example `message`:
 
 ```proto
+edition = "2023";
+
 message Person {
-  optional string name = 1;
-  optional int32 id = 2;
-  optional string email = 3;
+  string name = 1;
+  int32 id = 2;
+  string email = 3;
 }
 ```
 
@@ -103,10 +105,8 @@ The following languages are supported by Google, but the projects' source code
 resides in GitHub repositories. The protoc compiler uses plugins for these
 languages:
 
-<!-- mdformat off(mdformat adds a space between the ) and the {) -->
 *   [Dart](https://github.com/google/protobuf.dart)
 *   [Go](https://github.com/protocolbuffers/protobuf-go)
-<!-- mdformat on -->
 
 Additional languages are not directly supported by Google, but rather by other
 GitHub projects. These languages are covered in
@@ -127,9 +127,9 @@ and
 
 ### Updating Proto Definitions Without Updating Code {#updating-defs}
 
-It’s standard for software products to be backward compatible, but it is less
+It's standard for software products to be backward compatible, but it is less
 common for them to be forward compatible. As long as you follow some
-[simple practices](/programming-guides/proto3/#updating)
+[simple practices](/programming-guides/proto3#updating)
 when updating `.proto` definitions, old code will read new messages without
 issues, ignoring any newly added fields. To the old code, fields that were
 deleted will have their default value, and deleted repeated fields will be
@@ -159,8 +159,8 @@ Protocol buffers do not fit all data. In particular:
 *   Protocol buffer messages are less than maximally efficient in both size and
     speed for many scientific and engineering uses that involve large,
     multi-dimensional arrays of floating point numbers. For these applications,
-    [FITS](https://en.wikipedia.org/wiki/FITS) and similar formats
-    have less overhead.
+    [FITS](https://en.wikipedia.org/wiki/FITS) and similar formats have less
+    overhead.
 *   Protocol buffers are not well supported in non-object-oriented languages
     popular in scientific computing, such as Fortran and IDL.
 *   Protocol buffer messages don't inherently self-describe their data, but they
@@ -175,11 +175,9 @@ Protocol buffers do not fit all data. In particular:
 
 Many projects use protocol buffers, including the following:
 
-<!-- mdformat off(mdformat adds a space between the ) and the {) -->
-
 +   [gRPC](https://grpc.io)
 +   [Google Cloud](https://cloud.google.com)
-+   [Envoy Proxy](https://www.envoyproxy.io) <!-- mdformat on -->
++   [Envoy Proxy](https://www.envoyproxy.io)
 
 ## How do Protocol Buffers Work? {#work}
 
@@ -197,9 +195,9 @@ earlier, this is a `.proto` definition:
 
 ```proto
 message Person {
-  optional string name = 1;
-  optional int32 id = 2;
-  optional string email = 3;
+  string name = 1;
+  int32 id = 2;
+  string email = 3;
 }
 ```
 
@@ -230,14 +228,14 @@ std::string email = john.email();
 
 ## Protocol Buffers Definition Syntax {#syntax}
 
-When defining `.proto` files, you can specify that a field is either `optional`
-or `repeated` (proto2 and proto3) or leave it set to the default, implicit
-presence, in proto3. (The option to set a field to `required` is absent in
-proto3 and strongly discouraged in proto2. For more on this, see [Required Fields Considered Harmful](/programming-guides/required-considered-harmful.md).)
+When defining `.proto` files, you can specify cardinality (singular or
+repeated). In proto2 and proto3, you can also specify if the field is optional.
+In proto3, setting a field to optional
+[changes it from implicit presence to explicit presence](/programming-guides/field_presence).
 
-After setting the optionality/repeatability of a field, you specify the data
-type. Protocol buffers support the usual primitive data types, such as integers,
-booleans, and floats. For the full list, see
+After setting the cardinality of a field, you specify the data type. Protocol
+buffers support the usual primitive data types, such as integers, booleans, and
+floats. For the full list, see
 [Scalar Value Types](/programming-guides/proto3#scalar).
 
 A field can also be of:
@@ -249,16 +247,17 @@ A field can also be of:
     and at most one field will be set at the same time.
 *   A `map` type, to add key-value pairs to your definition.
 
-In proto2, messages can allow **extensions** to define fields outside of the
-message, itself. For example, the protobuf library's internal message schema
-allows extensions for custom, usage-specific options.
+Messages can allow **extensions** to define fields outside of the message,
+itself. For example, the protobuf library's internal message schema allows
+extensions for custom, usage-specific options.
 
 For more information about the options available, see the language guide for
-[proto2](/programming-guides/proto2) or
-[proto3](/programming-guides/proto3).
+[proto2](/programming-guides/proto2),
+[proto3](/programming-guides/proto3), or
+[edition 2023](/programming-guides/editions).
 
-After setting optionality and field type, you choose a name for the field.
-There are some things to keep in mind when setting field names:
+After setting cardinality and data type, you choose a name for the field. There
+are some things to keep in mind when setting field names:
 
 *   It can sometimes be difficult, or even impossible, to change field names
     after they've been used in production.
@@ -303,4 +302,4 @@ protobuf developers and users,
 ## Additional Resources {#additional-resources}
 
 *   [Protocol Buffers GitHub](https://github.com/protocolbuffers/protobuf/)
-*   [Codelabs](/getting-started/codelabs)
+    * [Tutorials](https://protobuf.dev/getting-started/)

content/programming-guides/proto2.md

@@ -676,7 +676,7 @@ value for that field. The default values are type-specific:
     [generated code guide](/reference/) for your language
     for details.
 *   For enums, the default value is the **first defined enum value**, which
-    should be 0 (recommended for compatibility with proto3). See
+    should be 0 (recommended for compatibility with open enums). See
     [Enum Default Value](#enum-default).
 
 The default value for repeated fields is empty (generally an empty list in the
@@ -930,10 +930,11 @@ project and use fully qualified names for all imports.
 ### Using proto3 Message Types {#proto3}
 
 It's possible to import
-[proto3](/programming-guides/proto3) message types and
-use them in your proto2 messages, and vice versa. However, proto2 enums cannot
-be used directly in proto3 syntax (it's okay if an imported proto2 message uses
-them).
+[proto3](/programming-guides/proto3) and
+[edition 2023](/programming-guides/editions) message
+types and use them in your proto2 messages, and vice versa. However, proto2
+enums cannot be used directly in proto3 syntax (it's okay if an imported proto2
+message uses them).
 
 ## Nested Types {#nested}
 
@@ -1857,11 +1858,11 @@ open source RPC system developed at Google. gRPC works particularly well with
 protocol buffers and lets you generate the relevant RPC code directly from your
 `.proto` files using a special protocol buffer compiler plugin. However, as
 there are potential compatibility issues between clients and servers generated
-with proto2 and proto3, we recommend that you use proto3 for defining gRPC
-services. You can find out more about proto3 syntax in the
-[Proto3 Language Guide](/programming-guides/proto3). If
-you do want to use proto2 with gRPC, you need to use version 3.0.0 or higher of
-the protocol buffers compiler and libraries.
+with proto2 and proto3, we recommend that you use proto3 or edition 2023 for
+defining gRPC services. You can find out more about proto3 syntax in the
+[Proto3 Language Guide](/programming-guides/proto3) and
+about edition 2023 in
+[Edition 2023 Language Guide](/programming-guides/editions).
 
 In addition to gRPC, there are also a number of ongoing third-party projects to
 develop RPC implementations for Protocol Buffers. For a list of links to

content/programming-guides/proto3.md

@@ -532,6 +532,7 @@ automatically generated class:
       </tr>
       <tr>
         <td>sint32</td>
+        <td>int32_t</td>
         <td>int</td>
         <td>int</td>
         <td>int32</td>
@@ -543,6 +544,7 @@ automatically generated class:
       </tr>
       <tr>
         <td>sint64</td>
+        <td>int64_t</td>
         <td>long</td>
         <td>int/long<sup>[4]</sup></td>
         <td>int64</td>

content/reference/protobuf/google.protobuf.md

@@ -1240,12 +1240,22 @@ A Timestamp represents a point in time independent of any time zone or calendar,
 represented as seconds and fractions of seconds at nanosecond resolution in UTC
 Epoch time. It is encoded using the Proleptic Gregorian Calendar which extends
 the Gregorian calendar backwards to year one. It is encoded assuming all minutes
-are 60 seconds long, i.e. leap seconds are \"smeared\" so that no leap second
+are 60 seconds long, i.e. leap seconds are "smeared" so that no leap second
 table is needed for interpretation. Range is from 0001-01-01T00:00:00Z to
 9999-12-31T23:59:59.999999999Z. By restricting to that range, we ensure that we
 can convert to and from RFC 3339 date strings. See
 <https://www.ietf.org/rfc/rfc3339.txt>.
 
+The Timestamp type is encoded as a string in the RFC 3339 format:
+"`{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z`", where `{year}` is
+always expressed using four digits while `{month}`, `{day}`, `{hour}`, `{min}`,
+and `{sec}` are zero-padded to two digits each. The fractional seconds, which
+can go up to 9 digits (that is, up to 1 nanosecond resolution), are optional.
+The "Z" suffix indicates the timezone ("UTC"); the timezone is required. A
+proto3 JSON serializer should always use UTC (as indicated by "Z") when printing
+the Timestamp type and a proto3 JSON parser should be able to accept both UTC
+and other timezones (as indicated by an offset).
+
 Example 1: Compute Timestamp from POSIX `time()`.
 
 ```cpp