Merge pull request #149 from Logofile/sync

Documentation updates

Author: Logofile

content/editions/features.md

@@ -238,6 +238,15 @@ This feature sets the behavior for encoding fields when serializing.
 This feature doesn't impact proto3 files, so this section doesn't have a before
 and after of a proto3 file.
 
+Depending on the language, fields that are "group-like" may have some unexpected
+capitalization in generated code and in text-format, in order to provide
+backwards compatibility with proto2. Message fields are "group-like" if all of
+the following conditions are met:
+
+*   Has `DELIMITED` message encoding specified
+*   Message type is defined in the same scope as the field
+*   Field name is exactly the lowercased type name
+
 **Values available:**
 
 *   `LENGTH_PREFIXED`: Fields are encoded using the LEN wire type described in
@@ -455,6 +464,78 @@ message Msg {
 }
 ```
 
+#### `features.(pb.cpp).string_type` {#string_type}
+
+**Languages:** C++
+
+This feature determines how generated code should treat string fields. This
+replaces the `ctype` option from proto2 and proto3, and offers a new
+`string_view` feature. In Edition 2023, either `ctype` or `string_view` may be
+specified on a field, but not both.
+
+**Values available:**
+
+*   `VIEW`: Generates `string_view` accessors for the field. This will be the
+    default in a future edition.
+*   `CORD`: Generates `Cord` accessors for the field.
+*   `STRING`: Generates `string` accessors for the field.
+
+**Applicable to the following scopes:** File, Field
+
+**Default behavior in Edition 2023:** `STRING`
+
+**Behavior in proto2:** `STRING`
+
+**Behavior in proto3:** `STRING`
+
+The following code sample shows a proto2 file:
+
+```proto
+syntax = "proto2";
+
+message Foo {
+  optional string bar = 6;
+  optional string baz = 7 [ctype = CORD];
+}
+```
+
+After running Prototiller, the equivalent code might look like this:
+
+```proto
+edition = "2023";
+
+import "google/protobuf/cpp_features.proto";
+
+message Foo {
+  optional string bar = 6;
+  optional string baz = 7 [features.(pb.cpp).string_type = CORD];
+}
+```
+
+The following shows a proto3 file:
+
+```proto
+syntax = "proto3"
+
+message Foo {
+  string bar = 6;
+  string baz = 7 [ctype = CORD];
+}
+```
+
+After running Prototiller, the equivalent code might look like this:
+
+```proto
+edition = "2023";
+
+import "google/protobuf/cpp_features.proto";
+
+message Foo {
+  string bar = 6;
+  string baz = 7 [features.(pb.cpp).string_type = CORD];
+}
+```
+
 #### `features.(pb.java).utf8_validation` {#java-utf8_validation}
 
 **Languages:** Java

content/getting-started/cpptutorial.md

@@ -16,7 +16,7 @@ shows you how to
 
 This isn't a comprehensive guide to using protocol buffers in C++. For more
 detailed reference information, see the
-[Protocol Buffer Language Guide (proto2)](/programming-guides/proto),
+[Protocol Buffer Language Guide (proto2)](/programming-guides/proto2),
 the
 [Protocol Buffer Language Guide (proto3)](/programming-guides/proto3),
 the [C++ API Reference](/reference/cpp/api-docs), the
@@ -169,7 +169,7 @@ most messages defined in proto2 syntax use `optional` and `repeated` only.
 
 You'll find a complete guide to writing `.proto` files -- including all the
 possible field types -- in the
-[Protocol Buffer Language Guide](/programming-guides/proto).
+[Protocol Buffer Language Guide](/programming-guides/proto2).
 Don't go looking for facilities similar to class inheritance, though -- protocol
 buffers don't do that.
 
@@ -557,7 +557,7 @@ some rules you need to follow. In the new version of the protocol buffer:
     buffer, not even by deleted fields).
 
 (There are
-[some exceptions](/programming-guides/proto#updating) to
+[some exceptions](/programming-guides/proto2#updating) to
 these rules, but they are rarely used.)
 
 If you follow these rules, old code will happily read new messages and simply

content/getting-started/javatutorial.md

@@ -16,7 +16,7 @@ shows you how to
 
 This isn't a comprehensive guide to using protocol buffers in Java. For more
 detailed reference information, see the
-[Protocol Buffer Language Guide (proto2)](/programming-guides/proto),
+[Protocol Buffer Language Guide (proto2)](/programming-guides/proto2),
 the
 [Protocol Buffer Language Guide (proto3)](/programming-guides/proto3),
 the
@@ -189,7 +189,7 @@ most messages defined in proto2 syntax use `optional` and `repeated` only.
 
 You'll find a complete guide to writing `.proto` files -- including all the
 possible field types -- in the
-[Protocol Buffer Language Guide](/programming-guides/proto).
+[Protocol Buffer Language Guide](/programming-guides/proto2).
 Don't go looking for facilities similar to class inheritance, though -- protocol
 buffers don't do that.
 
@@ -580,7 +580,7 @@ some rules you need to follow. In the new version of the protocol buffer:
     not even by deleted fields).
 
 (There are
-[some exceptions](/programming-guides/proto#updating) to
+[some exceptions](/programming-guides/proto2#updating) to
 these rules, but they are rarely used.)
 
 If you follow these rules, old code will happily read new messages and simply

content/getting-started/pythontutorial.md

@@ -16,7 +16,7 @@ shows you how to
 
 This isn't a comprehensive guide to using protocol buffers in Python. For more
 detailed reference information, see the
-[Protocol Buffer Language Guide (proto2)](/programming-guides/proto),
+[Protocol Buffer Language Guide (proto2)](/programming-guides/proto2),
 the
 [Protocol Buffer Language Guide (proto3)](/programming-guides/proto3),
 the [Python API Reference](https://googleapis.dev/python/protobuf/latest/), the
@@ -167,7 +167,7 @@ most messages defined in proto2 syntax use `optional` and `repeated` only.
 
 You'll find a complete guide to writing `.proto` files -- including all the
 possible field types -- in the
-[Protocol Buffer Language Guide](/programming-guides/proto).
+[Protocol Buffer Language Guide](/programming-guides/proto2).
 Don't go looking for facilities similar to class inheritance, though -- protocol
 buffers don't do that.
 
@@ -443,7 +443,7 @@ some rules you need to follow. In the new version of the protocol buffer:
     not even by deleted fields).
 
 (There are
-[some exceptions](/programming-guides/proto#updating) to
+[some exceptions](/programming-guides/proto2#updating) to
 these rules, but they are rarely used.)
 
 If you follow these rules, old code will happily read new messages and simply

content/news/2022-08-03.md

@@ -12,15 +12,15 @@ changes that are being considered for the 22.x release line.
 ## Platform Support Changes {#platform-changes}
 
 We've added guidance about the platforms that we support in
-[this section](/programming-guides/proto#platforms) of
+[this section](/programming-guides/proto2#platforms) of
 the documentation. The section currently covers C++ and PHP, but may be expanded
 with information about other platforms in the future.
 
 ## Official C++ Support Matrix {#cpp-support-matrix}
 
 With the policy, mentioned earlier in this announcement, of using Google's
 official
-[foundational C++ support policy](/programming-guides/proto#platforms),
+[foundational C++ support policy](/programming-guides/proto2#platforms),
 our
 [C++ compiler and toolchain support matrix will change](https://github.com/google/oss-policies-info/blob/8067c719150dfec6a836dd82230c5eb0ba11acd7/foundational-cxx-support-matrix.md).
 

content/news/_index.md

@@ -11,6 +11,10 @@ Buffers, and plans for upcoming changes. The information is available both
 chronologically and per-release. Note that not everything is included in the
 per-release topics, as some content is not tied to a version.
 
+New news topics will also be published to the
+[protobuf@](https://groups.google.com/g/protobuf) mailing list under the subject
+\[Announcement\].
+
 ## Chronological {#chronological}
 
 The following news topics provide information in the reverse order in which it

content/programming-guides/api.md

@@ -61,7 +61,7 @@ Document the constraints, expectations and interpretation of each field in as
 few words as possible.
 
 You can use custom proto annotations.
-See [Custom Options](/programming-guides/proto#options)
+See [Custom Options](/programming-guides/proto2#options)
 to define cross-language constants like `max_length` in the example above.
 Supported in proto2 and proto3.
 
@@ -291,7 +291,7 @@ worse—write one.
 
 More generally, choose the right primitive type. See the Scalar Value Types
 table in the
-[Protocol Buffer Language Guide](/programming-guides/proto#scalar).
+[Protocol Buffer Language Guide](/programming-guides/proto2#scalar).
 
 ### Returning HTML in a Front-End Proto {#returning-html}
 

content/programming-guides/enum.md

@@ -9,7 +9,7 @@ Enums behave differently in different language libraries. This topic covers the
 different behaviors as well as the plans to move protobufs to a state where they
 are consistent across all languages. If you're looking for information on how to
 use enums in general, see the corresponding sections in the
-[proto2](/programming-guides/proto#enum) and
+[proto2](/programming-guides/proto2#enum) and
 [proto3](/programming-guides/proto3#enum) language guide
 topics.
 

content/programming-guides/proto2.md

@@ -462,7 +462,7 @@ automatically generated class:
       </tr>
       <tr>
         <td>string</td>
-        <td>A string must always contain UTF-8 encoded or 7-bit ASCII text, and
+        <td>A string must always contain UTF-8 encoded<sup>[5]</sup> or 7-bit ASCII text, and
         cannot be longer than 2<sup>32</sup>.</td>
         <td>string</td>
         <td>String</td>
@@ -502,6 +502,10 @@ checking to make sure it is valid.
 when decoded, but can be an int if an int is given when setting the field. In
 all cases, the value must fit in the type represented when set. See [2].
 
+<sup>[5]</sup> Proto2 typically doesn't ever check the UTF-8 validity of string
+fields. Behavior varies between languages though, and invalid UTF-8 data should
+not be stored in string fields.
+
 You can find out more about how these types are encoded when you serialize your
 message in
 [Protocol Buffer Encoding](/programming-guides/encoding).

content/programming-guides/proto3.md

@@ -1076,6 +1076,8 @@ map<string, Project> projects = 3;
     field is serialized is language-dependent. In C++, Java, Kotlin, and Python
     the default value for the type is serialized, while in other languages
     nothing is serialized.
+*   No symbol `FooEntry` can exist in the same scope as a map `foo`, because
+    `FooEntry` is already used by the implementation of the map.
 
 The generated map API is currently available for all supported languages. You
 can find out more about the map API for your chosen language in the relevant