Merge pull request #76 from Logofile/sync

This CL contains primarily changes to the structure of the C++ API do…

Author: Logofile

content/news/2023-07-17.md

@@ -0,0 +1,15 @@
++++
+title = "Changes Announced on July 17, 2023"
+weight = 21
+linkTitle = "July 17, 2023"
+toc_hide = "true"
+description = "Changes announced for Protocol Buffers on July 17, 2023."
+type = "docs"
++++
+
+## Dropping Bazel 5.x Support
+
+As per our official
+[support policy](https://opensource.google/documentation/policies/cplusplus-support),
+we will be dropping support for Bazel 5.x and lower. This means the minimum
+supported Bazel version is 6.2.x.

content/news/_index.md

@@ -8,6 +8,8 @@ type = "docs"
 News topics provide information about past events and changes with Protocol
 Buffers, and plans for upcoming changes.
 
+*   [July 17, 2023](/news/2023-07-17) - Dropping support
+    for older versions of Bazel
 *   [July 6, 2023](/news/2023-07-06) - Dropping support
     for older versions of PHP, Ruby, and Python
 *   [June 29, 2023](/news/2023-06-29) - Protobuf Editions

content/overview.md

@@ -262,10 +262,19 @@ 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/proto) or
+[proto2](/programming-guides/proto2) or
 [proto3](/programming-guides/proto3).
 
-After setting optionality and field type, you assign a field number. Field
+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:
+
+*   It can sometimes be difficult, or even impossible, to change field names
+    after they've been used in production.
+*   Field names cannot contain dashes. For more on field name syntax, see
+    [Message and Field Names](/programming-guides/style#message-field-names).
+*   Use pluralized names for repeated fields.
+
+After assigning a name to the field, you assign a field number. Field
 numbers cannot be repurposed or reused. If you delete a field, you should
 reserve its field number to prevent someone from accidentally reusing the
 number.

content/programming-guides/dos-donts.md

@@ -171,12 +171,17 @@ For example:
     https://google.github.io/styleguide/cppguide.html#Namespace_Names.
     If these style guides conflict, use `java_package` for Java.
 
-## **Never** Use Text-format Messages for Interchange
+## **Don't** use Text Format Messages for Interchange
 
-Deserializing of text-format protocol buffers will fail when the binary is
-unaware of a field rename, a new field, or a new extension. In general,
-text-format is not future proof. Use text-format for human editing and debugging
-only.
+Text-based serialization formats like text format and
+JSON represent fields and enum values as strings. As a result, deserialization
+of protocol buffers in these formats using old code will fail when a field or
+enum value is renamed, or when a new field or enum value or extension is added.
+Use binary serialization when possible for data interchange, and use text format
+for human editing and debugging only.
+
+If you use protos converted to JSON in your API or for storing data, you may not
+be able to safely rename fields or enums at all.
 
 ## **Never** Rely on Serialization Stability Across Builds
 

content/programming-guides/encoding.md

@@ -483,10 +483,10 @@ Field numbers may be declared in any order in a `.proto` file. The order chosen
 has no effect on how the messages are serialized.
 
 When a message is serialized, there is no guaranteed order for how its known or
-[unknown fields](/programming-guides/proto#updating) will
-be written. Serialization order is an implementation detail, and the details of
-any particular implementation may change in the future. Therefore, protocol
-buffer parsers must be able to parse fields in any order.
+[unknown fields](/programming-guides/proto2#updating)
+will be written. Serialization order is an implementation detail, and the
+details of any particular implementation may change in the future. Therefore,
+protocol buffer parsers must be able to parse fields in any order.
 
 ### Implications {#implications}
 
@@ -541,7 +541,7 @@ i32        := sfixed32 | fixed32 | float;
                 memcpy of the equivalent C types (u?int32_t, float)
 i64        := sfixed64 | fixed64 | double;
                 encoded as 8-byte little-endian;
-                memcpy of the equivalent C types (u?int32_t, float)
+                memcpy of the equivalent C types (u?int64_t, double)
 
 len-prefix := size (message | string | bytes | packed);
                 size encoded as int32 varint

content/programming-guides/proto2.md

@@ -599,9 +599,14 @@ message SearchRequest {
   optional int32 result_per_page = 3 [default = 10];
   optional Corpus corpus = 4 [default = CORPUS_UNIVERSAL];
 }
-
 ```
 
+Because `SearchRequest` sets a default for the value of the `corpus` field, the
+`CORPUS_UNSPECIFIED` value will not be used as a default. It will still be used
+if a value of 0 is encountered on the wire. Other instances of the `Corpus` type
+that **don't** set a default would use the `CORPUS_UNSPECIFIED` value as the
+default.
+
 You can define aliases by assigning the same value to different enum constants.
 To do this you need to set the `allow_alias` option to `true`. Otherwise, the
 protocol buffer compiler generates a warning message when aliases are