Merge pull request #81 from Logofile/sync

This change record includes the following updates:

Author: Logofile

content/programming-guides/dos-donts.md

@@ -10,23 +10,29 @@ try to update them at the same time. One or the
 other may get rolled back. Don’t assume that you can make a breaking change and
 it'll be okay because the client and server are in sync.
 
-## **Don't** Re-use a Tag Number
+<a id="dont-re-use-a-tag-number"></a>
+
+## **Don't** Re-use a Tag Number {#reuse-number}
 
 Never re-use a tag number. It messes up deserialization. Even if you think no
 one is using the field, don’t re-use a tag number. If the change was live ever,
 there could be serialized versions of your proto in a log
 somewhere. Or there could be old code in another server that will break.
 
-## **Don't** Change the Type of a Field
+<a id="dont-change-the-type-of-a-field"></a>
+
+## **Don't** Change the Type of a Field {#change-type}
 
 Almost never change the type of a field; it'll mess up deserialization, same as
 re-using a tag number. The
-[protobuf docs](/programming-guides/proto#updating)
+[protobuf docs](/programming-guides/proto2#updating)
 outline a small number of cases that are okay (for example, going between
 `int32`, `uint32`, `int64` and `bool`). However, changing a field’s message type
 **will break** unless the new message is a superset of the old one.
 
-## **Don't** Add a Required Field
+<a id="dont-add-a-required-field"></a>
+
+## **Don't** Add a Required Field {#add-required}
 
 Never add a required field, instead add `// required` to document the API
 contract. Required fields are considered harmful by so many they were
@@ -36,7 +42,9 @@ and whether someone will be forced to fill in your required field with an empty
 string or zero in four years when it’s no longer logically required but the
 proto still says it is.
 
-## **Don't** Make a Message with Lots of Fields
+<a id="dont-make-a-message-with-lots-of-fields"></a>
+
+## **Don't** Make a Message with Lots of Fields {#lots-of-fields}
 
 Don't make a message with “lots” (think: hundreds) of fields. In C++ every field
 adds roughly 65 bits to the in-memory object size whether it’s populated or not
@@ -46,7 +54,9 @@ grows too large, the generated code may not even compile (for example, in Java
 there is a hard limit on the size of a method
 ).
 
-## **Do** Include an Unspecified Value in an Enum
+<a id="do-include-an-unspecified-value-in-an-enum"></a>
+
+## **Do** Include an Unspecified Value in an Enum {#unspecified-enum}
 
 Enums should include a default `FOO_UNSPECIFIED` value as the first value in the
 declaration . When new values
@@ -64,22 +74,28 @@ less code. Note that [proto enums][proto-enums] require the first value to be
 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
+[proto-enums]: /programming-guides/proto2#enum
 
-## **Don't** Use C/C++ Macro Constants for Enum Values
+<a id="dont-use-cc-macro-constants-for-enum-values"></a>
+
+## **Don't** Use C/C++ Macro Constants for Enum Values {#macro-constants}
 
 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
+<a id="do-use-well-known-types-and-common-types"></a>
+
+## **Do** Use Well-Known Types and Common Types {#well-known-common}
 
 Embedding the following common, shared types is strongly encouraged. Do not use
 `int32 timestamp_seconds_since_epoch` or `int64 timeout_millis` in your code
 when a perfectly suitable common type already exists!
 
-### Well-Known Types:
+<a id="well-known-types"></a>
+
+### Well-Known Types {#well-known}
 
 *   [duration](https://github.com/protocolbuffers/protobuf/blob/main/src/google/protobuf/duration.proto)
     is a signed, fixed-length span of time (for example, 42s).
@@ -89,7 +105,9 @@ when a perfectly suitable common type already exists!
 *   [field_mask](https://github.com/protocolbuffers/protobuf/blob/main/src/google/protobuf/field_mask.proto)
     is a set of symbolic field paths (for example, f.b.d).
 
-### Common Types:
+<a id="common-types"></a>
+
+### Common Types {#common}
 
 *   [interval](https://github.com/googleapis/googleapis/blob/master/google/type/interval.proto)
     is a time interval independent of time zone or calendar (for example,
@@ -113,36 +131,46 @@ when a perfectly suitable common type already exists!
 *   [month](https://github.com/googleapis/googleapis/blob/master/google/type/month.proto)
     is a month of year (for example, April).
 
-## **Do** Define Widely-used Message Types in Separate Files
+<a id="do-define-widely-used-message-types-in-separate-files"></a>
+
+## **Do** Define Widely-used Message Types in Separate Files {#separate-files}
 
 If you're defining message types or enums that you hope/fear/expect to be widely
 used outside your immediate team, consider putting them in their own file with
 no dependencies. Then it's easy for anyone to use those types without
 introducing the transitive dependencies in your other proto files.
 
-## **Do** Reserve Tag Numbers for Deleted Fields
+<a id="do-reserve-tag-numbers-for-deleted-fields"></a>
+
+## **Do** Reserve Tag Numbers for Deleted Fields {#reserve-tag-numbers}
 
 When you delete a field that's no longer used, reserve its tag number so that no
 one accidentally re-uses it in the future. Just `reserved 2, 3;` is enough. No
 type required (lets you trim dependencies!). You can also reserve names to avoid
 recycling now-deleted field names: `reserved "foo", "bar";`.
 
-## **Do** Reserve Numbers for Deleted Enum Values
+<a id="do-reserve-numbers-for-deleted-enum-values"></a>
+
+## **Do** Reserve Numbers for Deleted Enum Values {#reserve-deleted-numbers}
 
 When you delete an enum value that's no longer used, reserve its number so that
 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";`.
 
-## **Don't** Change the Default Value of a Field
+<a id="dont-change-the-default-value-of-a-field"></a>
+
+## **Don't** Change the Default Value of a Field {#change-default-value}
 
 Almost never change the default value of a proto field. This causes version skew
 between clients and servers. A client reading an unset value will see a
 different result than a server reading the same unset value when their builds
 straddle the proto change. Proto3 removed the ability to
 set default values.
 
-## **Don't** Go from Repeated to Scalar
+<a id="dont-go-from-repeated-to-scalar"></a>
+
+## **Don't** Go from Repeated to Scalar {#repeated-to-scalar}
 
 Although it won't cause crashes, you'll lose data. For JSON, a mismatch in
 repeatedness will lose the whole *message*. For numeric proto3 fields and proto2
@@ -154,7 +182,9 @@ 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 .
 
-## **Do** Follow the Style Guide for Generated Code
+<a id="do-follow-the-style-guide-for-generated-code"></a>
+
+## **Do** Follow the Style Guide for Generated Code {#follow-style-guide}
 
 Proto generated code is referred to in normal code. Ensure that options in
 `.proto` file do not result in generation of code which violate the style guide.
@@ -171,7 +201,9 @@ For example:
     https://google.github.io/styleguide/cppguide.html#Namespace_Names.
     If these style guides conflict, use `java_package` for Java.
 
-## **Don't** use Text Format Messages for Interchange
+<a id="never-use-text-format-messages-for-interchange"></a>
+
+## **Don't** use Text Format Messages for Interchange {#text-format-interchange}
 
 Text-based serialization formats like text format and
 JSON represent fields and enum values as strings. As a result, deserialization
@@ -183,13 +215,17 @@ 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
+<a id="never-rely-on-serialization-stability-across-builds"></a>
+
+## **Never** Rely on Serialization Stability Across Builds {#serialization-stability}
 
 The stability of proto serialization is not guaranteed across binaries or across
 builds of the same binary. Do not rely on it when, for example, building cache
 keys.
 
-## **Don't** Generate Java Protos in the Same Java Package as Other Code
+<a id="dont-generate-java-protos-in-the-same-java-package-as-other-code"></a>
+
+## **Don't** Generate Java Protos in the Same Java Package as Other Code {#generate-java-protos}
 
 Generate Java proto sources into a separate package from your hand-written Java
 sources. The `package`, `java_package` and `java_alt_api_package` options
@@ -200,9 +236,9 @@ A common practice is to generate your protos into a `proto` subpackage in your
 project that **only** contains those protos (that is, no hand-written source
 code).
 
-## Appendix
+## Appendix {#appendix}
 
-### API Best Practices
+### API Best Practices {#api-best-practices}
 
 This document lists only changes that are extremely likely to cause breakage.
 For higher-level guidance on how to craft proto APIs that grow gracefully see

content/programming-guides/encoding.md

@@ -370,10 +370,10 @@ concatenation) even if you do not know their types.
 
 ### Packed Repeated Fields {#packed}
 
-Starting in v2.1.0, `repeated` fields of
-[scalar type](/programming-guides/proto2#scalar) can be
-declared as "packed". In proto2 this is done using the field option
-`[packed=true]`. In proto3 it is the default.
+Starting in v2.1.0, `repeated` fields of a primitive type
+(any [scalar type](/programming-guides/proto2#scalar)
+that is not `string` or `bytes`) can be declared as "packed". In proto2 this is
+done using the field option `[packed=true]`. In proto3 it is the default.
 
 Instead of being encoded as one record per entry, they are encoded as a single
 `LEN` record that contains each element concatenated. To decode, elements are