Merge branch 'main' into patch-1

Author: Logofile

config.toml

@@ -1,7 +1,6 @@
 baseURL = 'https://protobuf.dev'
 languageCode = 'en-us'
 title = 'Protocol Buffers Documentation'
-sidebar_search_disable = true
 
 # Theme
 [module]
@@ -80,7 +79,7 @@ weight = 1
     # See a complete list of available styles at https://xyproto.github.io/splash/docs/all.html
     style = "tango"
     # Uncomment if you want your chosen highlight style used for code blocks without a specified language
-    # guessSyntax = "true"
+    guessSyntax = "true"
 
 # Everything below this are Site Params
 
@@ -148,7 +147,7 @@ navbar_translucent_over_cover_disable = false
 # Enable to show the side bar menu in its compact state.
 sidebar_menu_compact = false
 # Set to true to hide the sidebar search box (the top nav search box will still be displayed if search is enabled)
-sidebar_search_disable = false
+sidebar_search_disable = true
 
 # ui.sidebar_menu_compact = true
 ui.ul_show = 2

content/_index.md

@@ -36,7 +36,8 @@ message Person {
 </div>
 <div class="col-md">
 
-```proto
+```java
+// Java code
 Person john = Person.newBuilder()
     .setId(1234)
     .setName("John Doe")
@@ -51,7 +52,8 @@ john.writeTo(output);
 </div>
 <div class="col-md">
 
-```proto
+```cpp
+// C++ code
 Person john;
 fstream input(argv[1],
     ios::in | ios::binary);

content/getting-started/cpptutorial.md

@@ -127,13 +127,13 @@ if you want one of your fields to have one of a predefined list of values --
 here you want to specify that a phone number can be one of the following phone
 types: `MOBILE`, `HOME`, or `WORK`.
 
-The " = 1", " = 2" markers on each element identify the unique "tag" that field
-uses in the binary encoding. Tag numbers 1-15 require one less byte to encode
-than higher numbers, so as an optimization you can decide to use those tags for
-the commonly used or repeated elements, leaving tags 16 and higher for
-less-commonly used optional elements. Each element in a repeated field requires
-re-encoding the tag number, so repeated fields are particularly good candidates
-for this optimization.
+The " = 1", " = 2" markers on each element identify the unique field number that
+field uses in the binary encoding. Field numbers 1-15 require one less byte to
+encode than higher numbers, so as an optimization you can decide to use those
+numbers for the commonly used or repeated elements, leaving field numbers 16 and
+higher for less-commonly used optional elements. Each element in a repeated
+field requires re-encoding the field number, so repeated fields are particularly
+good candidates for this optimization.
 
 Each field must be annotated with one of the following modifiers:
 
@@ -550,12 +550,12 @@ your new buffers to be backwards-compatible, and your old buffers to be
 forward-compatible -- and you almost certainly do want this -- then there are
 some rules you need to follow. In the new version of the protocol buffer:
 
--   you *must not* change the tag numbers of any existing fields.
+-   you *must not* change the field numbers of any existing fields.
 -   you *must not* add or delete any required fields.
 -   you *may* delete optional or repeated fields.
--   you *may* add new optional or repeated fields but you must use fresh tag
-    numbers (that is, tag numbers that were never used in this protocol buffer,
-    not even by deleted fields).
+-   you *may* add new optional or repeated fields but you must use fresh field
+    numbers (that is, field numbers that were never used in this protocol
+    buffer, not even by deleted fields).
 
 (There are
 [some exceptions](/programming-guides/proto#updating) to
@@ -567,7 +567,7 @@ simply have their default value, and deleted repeated fields will be empty. New
 code will also transparently read old messages. However, keep in mind that new
 optional fields will not be present in old messages, so you will need to either
 check explicitly whether they're set with `has_`, or provide a reasonable
-default value in your `.proto` file with `[default = value]` after the tag
+default value in your `.proto` file with `[default = value]` after the field
 number. If the default value is not specified for an optional element, a
 type-specific default value is used instead: for strings, the default value is
 the empty string. For booleans, the default value is false. For numeric types,

content/getting-started/pythontutorial.md

@@ -326,62 +326,60 @@ the file again. The parts which directly call or reference code generated by the
 protocol compiler are highlighted.
 
 ```python
-#! /usr/bin/python
+#!/usr/bin/env python3
 
 import addressbook_pb2
 import sys
 
 # This function fills in a Person message based on user input.
 def PromptForAddress(person):
-  person.id = int(raw_input("Enter person ID number: "))
-  person.name = raw_input("Enter name: ")
+  person.id = int(input("Enter person ID number: "))
+  person.name = input("Enter name: ")
 
-  email = raw_input("Enter email address (blank for none): ")
+  email = input("Enter email address (blank for none): ")
   if email != "":
     person.email = email
 
   while True:
-    number = raw_input("Enter a phone number (or leave blank to finish): ")
+    number = input("Enter a phone number (or leave blank to finish): ")
     if number == "":
       break
 
     phone_number = person.phones.add()
     phone_number.number = number
 
-    type = raw_input("Is this a mobile, home, or work phone? ")
-    if type == "mobile":
+    phone_type = input("Is this a mobile, home, or work phone? ")
+    if phone_type == "mobile":
       phone_number.type = addressbook_pb2.Person.PhoneType.MOBILE
-    elif type == "home":
+    elif phone_type == "home":
       phone_number.type = addressbook_pb2.Person.PhoneType.HOME
-    elif type == "work":
+    elif phone_type == "work":
       phone_number.type = addressbook_pb2.Person.PhoneType.WORK
     else:
-      print "Unknown phone type; leaving as default value."
+      print("Unknown phone type; leaving as default value.")
 
 # Main procedure:  Reads the entire address book from a file,
 #   adds one person based on user input, then writes it back out to the same
 #   file.
 if len(sys.argv) != 2:
-  print "Usage:", sys.argv[0], "ADDRESS_BOOK_FILE"
+  print("Usage:", sys.argv[0], "ADDRESS_BOOK_FILE")
   sys.exit(-1)
 
 address_book = addressbook_pb2.AddressBook()
 
 # Read the existing address book.
 try:
-  f = open(sys.argv[1], "rb")
-  address_book.ParseFromString(f.read())
-  f.close()
+  with open(sys.argv[1], "rb") as f:
+    address_book.ParseFromString(f.read())
 except IOError:
-  print sys.argv[1] + ": Could not open file.  Creating a new one."
+  print(sys.argv[1] + ": Could not open file.  Creating a new one.")
 
 # Add an address.
 PromptForAddress(address_book.people.add())
 
 # Write the new address book back to disk.
-f = open(sys.argv[1], "wb")
-f.write(address_book.SerializeToString())
-f.close()
+with open(sys.argv[1], "wb") as f:
+  f.write(address_book.SerializeToString())
 ```
 
 ## Reading a Message {#reading-a-message}
@@ -391,40 +389,39 @@ information out of it! This example reads the file created by the above example
 and prints all the information in it.
 
 ```python
-#! /usr/bin/python
+#!/usr/bin/env python3
 
 import addressbook_pb2
 import sys
 
 # Iterates though all people in the AddressBook and prints info about them.
 def ListPeople(address_book):
   for person in address_book.people:
-    print "Person ID:", person.id
-    print "  Name:", person.name
+    print("Person ID:", person.id)
+    print("  Name:", person.name)
     if person.HasField('email'):
-      print "  E-mail address:", person.email
+      print("  E-mail address:", person.email)
 
     for phone_number in person.phones:
       if phone_number.type == addressbook_pb2.Person.PhoneType.MOBILE:
-        print "  Mobile phone #: ",
+        print("  Mobile phone #: ", end="")
       elif phone_number.type == addressbook_pb2.Person.PhoneType.HOME:
-        print "  Home phone #: ",
+        print("  Home phone #: ", end="")
       elif phone_number.type == addressbook_pb2.Person.PhoneType.WORK:
-        print "  Work phone #: ",
-      print phone_number.number
+        print("  Work phone #: ", end="")
+      print(phone_number.number)
 
 # Main procedure:  Reads the entire address book from a file and prints all
 #   the information inside.
 if len(sys.argv) != 2:
-  print "Usage:", sys.argv[0], "ADDRESS_BOOK_FILE"
+  print("Usage:", sys.argv[0], "ADDRESS_BOOK_FILE")
   sys.exit(-1)
 
 address_book = addressbook_pb2.AddressBook()
 
 # Read the existing address book.
-f = open(sys.argv[1], "rb")
-address_book.ParseFromString(f.read())
-f.close()
+with open(sys.argv[1], "rb") as f:
+  address_book.ParseFromString(f.read())
 
 ListPeople(address_book)
 ```

content/includes/version-tables.css

@@ -0,0 +1,34 @@
+table tbody, th, td {
+  border: 1px solid #818589 !important;
+  padding-top: 2px;
+  padding-bottom: 2px;
+  padding-left: 5px;
+  padding-right: 5px;
+  text-align: center;
+
+}
+
+tbody td {
+  background: #fff;
+}
+
+tbody td.red {
+  background: #f00;
+  color: #fff;
+}
+
+tbody td.blue {
+  background: #c9daf8;
+}
+
+tbody td.green {
+  background: #d9ead3;
+}
+
+tbody td.gray {
+  background: #f3f3f3;
+}
+
+tbody td.yellow {
+  background: #fff2cc;
+}

content/news/2022-08-03.md

@@ -88,9 +88,3 @@ automatically generated by GitHub on the release page.
 
 In 22.0 we plan to rename Maven artifacts to use “RC” instead of “rc-” as the
 release candidate prefix.
-
-### Releasing Only Ruby Source Gems {#gems}
-
-We currently release multiple Ruby gems that are compiled for different
-architectures. Starting in 22.0, we plan to release only a single ruby source
-gem that contains source code and will be compiled on the host system.

content/programming-guides/api.md

@@ -668,6 +668,10 @@ system."
 If the enhancement field in `PhotoEnhancementReply` were a scalar or enum, this
 would be much harder to support.
 
+This applies equally to maps. It is much easier to add additional fields to a
+map value if it's already a message rather than having to migrate from
+`map<string, string>` to `map<string, MyProto>`.
+
 One exception:
 
 Latency-critical applications will find parallel arrays of primitive types are

content/programming-guides/dos-donts.md

@@ -166,9 +166,15 @@ For example:
 
 *   `java_outer_classname` should follow
     https://google.github.io/styleguide/javaguide.html#s5.2.2-class-names
+
 *   `java_package` and `java_alt_package` should follow
     https://google.github.io/styleguide/javaguide.html#s5.2.1-package-names
 
+*   `package`, although used for Java when `java_package` is not present, always
+    directly corresponds to C++ namespace and thus should follow
+    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
 
 Deserializing of text-format protocol buffers will fail when the binary is

content/programming-guides/encoding.md

@@ -183,11 +183,13 @@ This is the *two's complement* of 2, defined in unsigned arithmetic as `~0 - 2 +
 1`, where `~0` is the all-ones 64-bit integer. It is a useful exercise to
 understand why this produces so many ones.
 
-On the other hand, `sintN` uses the "ZigZag" encoding instead of two's
-complement to encode negative integers. Positive integers `n` are encoded as `2
-* n` (the even numbers), while negative integers `-n` are encoded as `2 * n + 1`
-(the odd numbers). The encoding thus "zig-zags" between positive and negative
-numbers. For example:
+<!-- mdformat off(the asterisks cause bullets) -->
+`sintN` uses the "ZigZag" encoding instead of two's complement to encode
+negative integers. Positive integers `n` are encoded as `2 * n` (the even
+numbers), while negative integers `-n` are encoded as `2 * n + 1` (the odd
+numbers). The encoding thus "zig-zags" between positive and negative numbers.
+For example:
+<!-- mdformat on -->
 
 Signed Original | Encoded As
 --------------- | ----------
@@ -202,7 +204,7 @@ Signed Original | Encoded As
 Using some bit tricks, it's cheap to convert `n` into its ZigZag representation:
 
 ```
-n + n + (n < 0)
+((n + n) ^ -(n < 0)) - (n < 0)
 ```
 
 Here, we assume that the boolean `n < 0` is converted into an integer 1 if true
@@ -294,7 +296,7 @@ Missing `optional` fields are easy to encode: we just leave out the record if
 it's not present. This means that "huge" protos with only a few fields set are
 quite sparse.
 
-`repeated` fields are a bit more compicated. Ordinary (not [packed](#packed))
+`repeated` fields are a bit more complicated. Ordinary (not [packed](#packed))
 repeated fields emit one record for every element of the field. Thus, if we have
 
 ```proto