Merge the changes made internally to docs into the external documentation

site.

Author: Logofile

.github/workflows/gh-pages.yml

@@ -19,7 +19,10 @@ jobs:
         uses: peaceiris/actions-hugo@v2
         with:
           hugo-version: 'latest'
-          # extended: true
+          extended: true
+          
+      - name: Install Dependencies
+        run: npm install autoprefixer postcss postcss-cli
 
       - name: Build
         run: hugo --minify
@@ -29,4 +32,5 @@ jobs:
         if: github.ref == 'refs/heads/main'
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
-          publish_dir: ./public
+          publish_dir: ./public
+          cname: protobuf.dev

config.toml

@@ -1,4 +1,4 @@
-# baseURL = 'https://protobuf.dev'
+baseURL = 'https://protobuf.dev'
 languageCode = 'en-us'
 title = 'Protocol Buffers Documentation'
 sidebar_search_disable = true
@@ -119,9 +119,6 @@ github_repo = "https://github.com/protocolbuffers/protocolbuffers.github.io"
 # An optional link to a related project repo. For example, the sibling repository where your product code lives.
 github_project_repo = "https://github.com/protocolbuffers/protobuf"
 
-# Specify a value here if your content directory is not in your repo's root directory
-github_subdir = "/docs"
-
 # Uncomment this if you have a newer GitHub repo with "main" as the default branch,
 # or specify a new value if you want to reference another branch in your GitHub links
 # github_branch= "main"
@@ -145,7 +142,7 @@ breadcrumb_disable = false
 # Set to true to disable the About link in the site footer
 footer_about_disable = false
 # Set to false if you don't want to display a logo (/assets/icons/logo.svg) in the top navbar
-navbar_logo = true
+navbar_logo = false
 # Set to true if you don't want the top navbar to be translucent when over a `block/cover`, like on the homepage.
 navbar_translucent_over_cover_disable = false
 # Enable to show the side bar menu in its compact state.
@@ -191,4 +188,4 @@ enable = false
   name = "Developer mailing list"
   url = "https://groups.google.com/g/protobuf"
   icon = "fa fa-envelope"
-  desc = "Discuss development issues around the project"
+  desc = "Discuss development issues around the project"

content/programming-guides/dos-donts.md

@@ -70,6 +70,13 @@ zero and can round-trip (deserialize, serialize) an unknown enum value.
 [example-unspecified]: http://cs/#search/&q=file:proto%20%22_UNSPECIFIED%20=%200%22&type=cs
 [proto-enums]: /programming-guides/proto#enum
 
+## **Don't** Use C/C++ Macro Constants for Enum Values
+
+Using words that have already been defined by the C++ language - specifically,
+in its headers such as `math.h`, may cause compilation errors if the `#include`
+statement for one of those headers appears before the one for `.proto.h`. Avoid
+using macro constants such as "`NULL`," "`NAN`," and "`DOMAIN`" as enum values.
+
 ## **Do** Use Well-Known Types and Common Types
 
 Embedding the following common, shared types is strongly encouraged. Do not use
@@ -151,18 +158,6 @@ Going from scalar to repeated is OK in proto2 and in proto3 with
 `[packed=false]` because for binary serialization the scalar value becomes a
 one-element list .
 
-## **Always** Create a Build Rule for Your Proto Files
-
-If your proto is only used by a script that doesn't require a build rule, create
-a `proto_library` rule with an associated
-`build_test` rule.
-
-With a `build_test` rule, errors in the file are caught when the test fails.
-Otherwise, typos and errors can persist and lead to hard-to-diagnose
-problems. Adding this `build_test` to
-your build script is also highly recommended, so you
-can be notified of future breakages.
-
 ## **Do** Follow the Style Guide for Generated Code
 
 Proto generated code is referred to in normal code. Ensure that options in

content/programming-guides/proto.md

@@ -829,11 +829,14 @@ the following rules:
     recognized and newly-added values, which means that order will not be
     preserved.
 *   Changing a single `optional` field or extension into a member of a **new**
-    `oneof` is safe and binary compatible. Moving multiple `optional` fields
-    into a new `oneof` may be safe if you are sure that no code sets more than
-    one at a time. Moving any fields into an existing `oneof` is not safe.
-    Likewise, changing a single field `oneof` to an `optional` field or
-    extension is safe.
+    `oneof` is binary compatible, however for some languages (notably, Go) the
+    generated code's API will change in incompatible ways. For this reason,
+    Google does not make such changes in its public APIs, as documented in
+    [AIP-180](https://google.aip.dev/180#moving-into-oneofs). With
+    the same caveat about source-compatibility, moving multiple fields into a
+    new `oneof` may be safe if you are sure that no code sets more than one at a
+    time. Moving fields into an existing `oneof` is not safe. Likewise, changing
+    a single field `oneof` to an `optional` field or extension is safe.
 *   Changing a field between a `map<K, V>` and the corresponding `repeated`
     message field is binary compatible (see [Maps](#maps), below, for the
     message layout and other restrictions). However, the safety of the change is
@@ -1082,7 +1085,7 @@ wire is a member of the oneof.
     information (some fields will be cleared) after the message is serialized
     and parsed. However, you can safely move a single field into a **new** oneof
     and may be able to move multiple fields if it is known that only one is ever
-    set.
+    set. See [Updating A Message Type](#updating) for further details.
 *   **Delete a oneof field and add it back**: This may clear your currently set
     oneof field after the message is serialized and parsed.
 *   **Split or merge oneof**: This has similar issues to moving regular
@@ -1442,8 +1445,9 @@ Here are a few of the most commonly used options:
 
 *   `deprecated` (field option): If set to `true`, indicates that the field is
     deprecated and should not be used by new code. In most languages this has no
-    actual effect. In Java, this becomes a `@Deprecated` annotation. In the
-    future, other language-specific code generators may generate deprecation
+    actual effect. In Java, this becomes a `@Deprecated` annotation. For C++,
+    clang-tidy will generate warnings whenever deprecated fields are used. In
+    the future, other language-specific code generators may generate deprecation
     annotations on the field's accessors, which will in turn cause a warning to
     be emitted when compiling code which attempts to use the field. If the field
     is not used by anyone and you want to prevent new users from using it,

content/programming-guides/proto3.md

@@ -948,10 +948,14 @@ following rules:
     deserialized is language-dependent. Int fields always just preserve their
     value.
 *   Changing a single `optional` field or extension into a member of a **new**
-    `oneof` is safe and binary compatible. Moving multiple fields into a new
-    `oneof` may be safe if you are sure that no code sets more than one at a
-    time. Moving any fields into an existing `oneof` is not safe. Likewise,
-    changing a single field `oneof` to an `optional` field or extension is safe.
+    `oneof` is binary compatible, however for some languages (notably, Go) the
+    generated code's API will change in incompatible ways. For this reason,
+    Google does not make such changes in its public APIs, as documented in
+    [AIP-180](https://google.aip.dev/180#moving-into-oneofs). With
+    the same caveat about source-compatibility, moving multiple fields into a
+    new `oneof` may be safe if you are sure that no code sets more than one at a
+    time. Moving fields into an existing `oneof` is not safe. Likewise, changing
+    a single field `oneof` to an `optional` field or extension is safe.
 
 ## Unknown Fields {#unknowns}
 
@@ -1116,7 +1120,7 @@ wire is a member of the oneof.
     information (some fields will be cleared) after the message is serialized
     and parsed. However, you can safely move a single field into a **new** oneof
     and may be able to move multiple fields if it is known that only one is ever
-    set.
+    set. See [Updating A Message Type](#updating) for further details.
 *   **Delete a oneof field and add it back**: This may clear your currently set
     oneof field after the message is serialized and parsed.
 *   **Split or merge oneof**: This has similar issues to moving regular fields.
@@ -1263,12 +1267,19 @@ Proto3 supports a canonical encoding in JSON, making it easier to share data
 between systems. The encoding is described on a type-by-type basis in the table
 below.
 
-If a value is missing in the JSON-encoded data or if its value is `null`, it
-will be interpreted as the appropriate [default value](#default) when parsed
-into a protocol buffer. If a field has the default value in the protocol buffer,
-it will be omitted in the JSON-encoded data by default to save space. An
-implementation may provide options to emit fields with default values in the
-JSON-encoded output.
+When parsing JSON-encoded data into a protocol buffer, if a value is missing or
+if its value is `null`, it will be interpreted as the corresponding
+[default value](#default).
+
+When generating JSON-encoded output from a protocol buffer, if a protobuf field
+has the default value and if the field doesn't support field presence, it will
+be omitted from the output by default. An implementation may provide options to
+include fields with default values in the output.
+
+A proto3 field that is defined with the `optional` keyword supports field
+presence. Fields that have a value set and that support field presence always
+include the field value in the JSON-encoded output, even if it is the default
+value.
 
 <table>
   <tbody>
@@ -1557,8 +1568,9 @@ Here are a few of the most commonly used options:
 
 *   `deprecated` (field option): If set to `true`, indicates that the field is
     deprecated and should not be used by new code. In most languages this has no
-    actual effect. In Java, this becomes a `@Deprecated` annotation. In the
-    future, other language-specific code generators may generate deprecation
+    actual effect. In Java, this becomes a `@Deprecated` annotation. For C++,
+    clang-tidy will generate warnings whenever deprecated fields are used. In
+    the future, other language-specific code generators may generate deprecation
     annotations on the field's accessors, which will in turn cause a warning to
     be emitted when compiling code which attempts to use the field. If the field
     is not used by anyone and you want to prevent new users from using it,

content/reference/_index.md

@@ -42,6 +42,7 @@ details, see [Other Languages](/reference/other).
 
 -   [Go Generated Code Guide](/reference/go/go-generated)
 -   [Go API (godoc)](https://pkg.go.dev/google.golang.org/protobuf/proto)
+    
 -   [Go FAQ](/reference/go/faq)
 
 ### Java Reference
@@ -61,6 +62,7 @@ details, see [Other Languages](/reference/other).
 ### PHP Reference
 
 -   [PHP Generated Code Guide](/reference/php/php-generated)
+-   [PHP API](/reference/php/api-docs)
 
 ### Python Reference
 

content/reference/cpp/_index.md

@@ -12,4 +12,4 @@ description: "This section contains reference documentation for working with pro
 *   [C++ Generated Code Guide](/reference/cpp/cpp-generated)
 *   [C++ Arena Allocation Guide](/reference/cpp/arenas)
 
-*   [C++ API](/reference/cpp)
+*   [C++ API](/reference/cpp/api-docs)

content/reference/php/_index.md

@@ -10,3 +10,4 @@ description: "This section contains reference documentation for working with pro
 
 
 *   [PHP Generated Code Guide](/reference/php/php-generated)
+*   [PHP API](/reference/php/api-docs)

content/reference/php/api-docs-link.md

@@ -0,0 +1,8 @@
+<!-- mdformat global-off -->
+
+---
+title: "PHP API"
+manualLink: "/reference/php/api-docs/"
+manualLinkTarget: "_blank"
+weight: 530
+---

content/reference/php/api-docs/DOCTUM_VERSION

@@ -0,0 +1 @@
+5.5.1