Merge pull request #226 from Logofile/sync

Documentation change

Author: Logofile

content/best-practices/api.md

@@ -294,7 +294,7 @@ More generally, choose the right primitive type. See the Scalar Value Types
 table in the
 [Protocol Buffer Language Guide](/programming-guides/proto2#scalar).
 
-### Returning HTML in a Front-End Proto {#returning-html}
+### Don't Return HTML in a Front-End Proto {#returning-html}
 
 With a JavaScript client, it's tempting to return HTML or
 JSON in a field of your API. This is a slippery
@@ -408,7 +408,7 @@ message InternalPaginationToken {
 }
 ```
 
-## Group Related Fields into a New Message. Nest Only Fields with High Cohesion {#group-related-fields}
+## Group Related Fields into a new `message`. Nest Only Fields with High Cohesion {#group-related-fields}
 
 ```proto
 message Foo {

content/best-practices/dos-donts.md

@@ -38,6 +38,29 @@ no one accidentally re-uses it in the future. Just `reserved 2, 3;` is enough.
 You can also reserve names to avoid recycling now-deleted value names: `reserved
 "FOO", "BAR";`.
 
+<a id="do-put-new-enum-aliases-last"></a>
+
+## **Do** Put New Enum Aliases Last {#enum-aliases-last}
+
+When you add a new enum alias, put the new name last to give
+services time to pick it up.
+
+To safely remove the original name (if it's being used for interchange, which it
+[shouldn't](#text-format-interchange)), you must do the following:
+
+*   Add the new name below the old name and deprecate the old one (serializers
+    will continue to use the old name)
+
+*   After every parser has the schema rolled out, swap the order of the two
+    names (serializers will begin using the new name, parsers accept both)
+
+*   After every serializer has that version of the schema, you can delete the
+    deprecated name.
+
+> **Note:** While in theory clients shouldn't be using the old name for
+> interchange, it's still polite to follow the above steps, especially for
+> widely-used enum names.
+
 <a id="dont-change-the-type-of-a-field"></a>
 
 ## **Don't** Change the Type of a Field {#change-type}

content/design-decisions/_index.md

@@ -0,0 +1,17 @@
++++
+title = "Protobuf Team Design Decisions"
+weight = 88
+description = "Covers the design decisions the Protobuf team has made"
+type = "docs"
+no_list = "true"
+linkTitle = "Design Decisions"
++++
+
+This section contains some positions of the Protobuf team that inform our design
+and implementation decisions.
+
+These positions were taken after careful consideration and won't be overturned
+on a whim, but are open to being revisited as we gain new information, and as
+things develop in the broader ecosystem context.
+
+*   [No Nullable Setters/Getters](/design-decisions/nullable-getters-setters)

…mming-guides/nullable-getters-setters.md …gn-decisions/nullable-getters-setters.mdcontent/programming-guides/nullable-getters-setters.md renamed to content/design-decisions/nullable-getters-setters.md content/programming-guides/nullable-getters-setters.md renamed to content/design-decisions/nullable-getters-setters.md

@@ -3,6 +3,7 @@ title = "No Nullable Setters/Getters Support"
 weight = 89
 description = "Covers why Protobuf doesn't support nullable setters and getters"
 type = "docs"
+aliases = "/programming-guides/nullable-getters-setters/"
 +++
 
 We have heard feedback that some folks would like protobuf to support nullable
@@ -15,6 +16,11 @@ The biggest reason not to have nullable fields is the intended behavior of
 default values specified in a `.proto` file. By design, calling a getter on an
 unset field will return the default value of that field.
 
+**Note:** C# does treat *message* fields as nullable. This inconsistency with
+other languages stems from the lack of immutable messages, which makes it
+impossible to create shared immutable default instances. Because message fields
+can't have defaults, there's no functional problem with this.
+
 As an example, consider this `.proto` file:
 
 ```proto

content/installation.md

@@ -0,0 +1,83 @@
++++
+title = "Protocol Buffer Compiler Installation"
+weight = 15
+description = "How to install the protocol buffer compiler."
+type = "docs"
+no_list = "true"
+linkTitle = "Protoc Installation"
++++
+
+The protocol buffer compiler, `protoc`, is used to compile `.proto` files, which
+contain service and message definitions. Choose one of the methods given below
+to install `protoc`.
+
+### Install Pre-compiled Binaries (Any OS) {#binary-install}
+
+To install the latest release of the protocol compiler from pre-compiled
+binaries, follow these instructions:
+
+1.  From https://github.com/google/protobuf/releases, manually download the zip
+    file corresponding to your operating system and computer architecture
+    (`protoc-<version>-<os>-<arch>.zip`), or fetch the file using commands such
+    as the following:
+
+    ```sh
+    PB_REL="https://github.com/protocolbuffers/protobuf/releases"
+    curl -LO $PB_REL/download/v< param protoc-version >/protoc-< param protoc-version >-linux-x86_64.zip
+    ```
+
+2.  Unzip the file under `$HOME/.local` or a directory of your choice. For
+    example:
+
+    ```sh
+    unzip protoc-< param protoc-version >-linux-x86_64.zip -d $HOME/.local
+    ```
+
+3.  Update your environment's path variable to include the path to the `protoc`
+    executable. For example:
+
+    ```sh
+    export PATH="$PATH:$HOME/.local/bin"
+    ```
+
+### Install Using a Package Manager {#package-manager}
+
+{{% alert title="Warning" color="warning" %}} Run
+`protoc --version` to check the version of `protoc` after using a package
+manager for installation to ensure that it is sufficiently recent. The versions
+of `protoc` installed by some package managers can be quite dated. See the
+[Version Support page](https://protobuf.dev/support/version-support) to compare
+the output of the version check to the minor version number of the supported
+version of the language(s) you are
+using.{{% /alert %}}
+
+You can install the protocol compiler, `protoc`, with a package manager under
+Linux, macOS, or Windows using the following commands.
+
+-   Linux, using `apt` or `apt-get`, for example:
+
+    ```sh
+    apt install -y protobuf-compiler
+    protoc --version  # Ensure compiler version is 3+
+    ```
+
+-   MacOS, using [Homebrew](https://brew.sh):
+
+    ```sh
+    brew install protobuf
+    protoc --version  # Ensure compiler version is 3+
+    ```
+
+-   Windows, using
+    [Winget](https://learn.microsoft.com/en-us/windows/package-manager/winget/)
+
+    ```sh
+    > winget install protobuf
+    > protoc --version # Ensure compiler version is 3+
+    ```
+
+### Other Installation Options {#other}
+
+If you'd like to build the protocol compiler from sources, or access older
+versions of the pre-compiled binaries, see
+[Download Protocol Buffers](https://protobuf.dev/downloads).

content/news/v30.md

@@ -55,7 +55,7 @@ be parseable by Protobuf TextFormat Parsers.
 Read more about this in the
 [news article released November 21, 2024](/news/2024-11-21).
 
-### Removing a a Reflection-related Function {#removing-mutable-repeated}
+### Removing a Reflection-related Function {#removing-mutable-repeated}
 
 We are removing the following reflection-related function:
 `MutableRepeatedFieldRef<T>::Reserve()`.

content/programming-guides/deserialize-debug.md

@@ -5,13 +5,14 @@ description = "How to log debugging information in Protocol Buffers."
 type = "docs"
 +++
 
-From version 29.x, `DebugString` APIs (`proto2::DebugString`,
-`proto2::ShortDebugString`, `proto2::Utf8DebugString`) are deprecated.
-DebugString users should migrate to some Abseil string functions (such as
-`absl::StrCat`, `absl::StrFormat`, `absl::StrAppend`, AND `absl::Substitute`),
-Abseil logging API, and some Protobuf APIs (`proto2::ShortFormat`,
-`proto2::Utf8Format`) to automatically convert proto arguments into a new
-debugging format .
+From version 30.x, Protobuf `DebugString` APIs (`Message::DebugString`,
+`Message::ShortDebugString`, `Message::Utf8DebugString`), additional Protobuf
+APIs (`proto2::ShortFormat`, `proto2::Utf8Format`), Abseil string functions
+(such as `absl::StrCat`, `absl::StrFormat`, `absl::StrAppend`, and
+`absl::Substitute`), and Abseil logging API will begin to automatically convert
+proto arguments into a new debugging format
+. See the related announcement
+[here](/news/2024-12-04/).
 
 Unlike the Protobuf DebugString output format, the new debugging format
 automatically redacts sensitive fields by replacing their values with the string
@@ -36,8 +37,7 @@ DebugString format in two ways:
     "[REDACTED]" (without the quotes)
 
 The new debugging format never removes any field names; it only replaces the
-value with
-"[REDACTED]" if the field is considered sensitive.
+value with "[REDACTED]" if the field is considered sensitive.
 **If you don't see certain fields in the output, it is because those fields are
 not set in the proto.**
 
@@ -83,8 +83,8 @@ systems can change and code gets re-used.
 This is intentional. Don't attempt to parse the output of this debug format. We
 reserve the right to change the syntax without notice. The debug format syntax
 randomly changes per process to prevent inadvertent dependencies. If a syntactic
-change in the debug format would break your system, chances are you shouldn't
-use the debug representation of a proto.
+change in the debug format would break your system, chances are you should be
+using a TextFormat API rather than using the debug representation of a proto.
 
 ## FAQ
 

content/programming-guides/field_presence.md

@@ -52,7 +52,6 @@ deserializing wire-formatted messages:
     -   For enums, the default is the zero-valued enumerator.
     -   For strings, bytes, and repeated fields, the default is the zero-length
         value.
-    -   For messages, the default is the language-specific null value.
 -   "Empty" length-delimited values (such as empty strings) can be validly
     represented in serialized values: the field is "present," in the sense that
     it appears in the wire format. However, if the generated API does not track
@@ -588,7 +587,7 @@ if (m.hasFoo()) {
 Implicit presence:
 
 ```objective-c
-Msg *m = [[Msg alloc] init];
+Msg *m = [Msg message];
 if (m.foo != 0) {
   // "Clear" the field:
   m.foo = 0;
@@ -601,13 +600,13 @@ if (m.foo != 0) {
 Explicit presence:
 
 ```objective-c
-Msg *m = [[Msg alloc] init];
-if (m.hasFoo()) {
+Msg *m = [Msg message];
+if ([m hasFoo]) {
   // Clear the field:
   [m clearFoo];
 } else {
   // Field is not present, so set it.
-  [m setFoo:1];
+  m.foo = 1;
 }
 ```
 
@@ -639,9 +638,9 @@ Repeated field & map   | no
 
 Is field presence tracked?
 
-Field type                                         | Tracked?
--------------------------------------------------- | --------
-Default                                            | yes
-`features.field_presence` set to `LEGACY_REQUIRED` | yes
-`features.field_presence` set to `IMPLICIT`        | no
-Repeated field & map                               | no
+Field type (in descending prescendence)                              | Tracked?
+-------------------------------------------------------------------- | --------
+Repeated field & map                                                 | no
+Message and Oneof fields                                             | yes
+Other singular fields if `features.field_presence` set to `IMPLICIT` | no
+All other fields                                                     | yes

content/programming-guides/proto2.md

@@ -2008,12 +2008,12 @@ Here are a few of the most commonly used options:
     numeric type, it causes a more compact
     [encoding](/programming-guides/encoding#packed) to be
     used. The only reason to not use this option is if you need compatibility
-    with parsers prior to version 2.3.0. When these older parsers would ignore
-    packed data when it was not expected. Therefore, it was not possible to
-    change an existing field to packed format without breaking wire
-    compatibility. In 2.3.0 and later, this change is safe, as parsers for
-    packable fields will always accept both formats, but be careful if you have
-    to deal with old programs using old protobuf versions.
+    with parsers prior to version 2.3.0. These older parsers would ignore packed
+    data when it was not expected. Therefore, it was not possible to change an
+    existing field to packed format without breaking wire compatibility. In
+    2.3.0 and later, this change is safe, as parsers for packable fields will
+    always accept both formats, but be careful if you have to deal with old
+    programs using old protobuf versions.
 
     ```proto
     repeated int32 samples = 4 [packed = true];