Sync Protocol Style
General guidelines:
- Follow the Protocol Buffers Style Guide
- Follow the Proto Do’s and Don’ts (sorry, Googlers only).
- Maintain local consistency.
- Use proto2 syntax.
- Always get a review from someone in the OWNERS file in this folder. Don’t use owners from higher-level folders, and never TBR changes!
Some specific guidelines on top of the general ones above, or just things that often come up:
- Enum entries should be in ALL_CAPS (different from C++!), and for new code, the first entry should be a
FOO_UNSPECIFIED = 0
one.
- Timestamp fields must specify their epoch and unit in a suffix, in this format:
_[unix|windows]_epoch_[seconds|millis|micros|nanos]
, e.g creation_time_unix_epoch_millis
.
- Many existing fields do not follow this format, and specify epoch/unit in a comment instead. Follow the format for all new fields, though!
- Similarly, duration fields must specify their unit as
_[minutes|seconds|millis|...]
.
- Proto changes also require corresponding changes in proto_visitors.h and (where appropriate) in proto_enum_conversions.h/cc.
- Backwards compatibility: In general, all changes must be fully backwards-compatible - consider that a single user might be running different versions of the browser simultaneously! Also note that Sync supports clients up to a few years old, so deprecating/removing an existing field is typically a multi-year process.
- As one special case, renaming a field within a specifics message is generally safe (unless there are special server-side integrations that depend on the name). However, never rename fields anywhere outside of specifics.
- Deprecating fields:
- If the field is still accessed: Mark it as
[deprecated = true]
. This is the common case, since the browser typically needs to continue supporting the old field for backwards compatibility reasons.
- If the field is not accessed anymore (i.e. no non-ancient clients depend on the field being populated anymore, all migration code has been retired, etc): Remove the field, and add
reserved
entries for both its name and its tag number.
- Deprecating enum values: This is particularly tricky, especially if the default value is not a
FOO_UNSPECIFIED
one (see above). A common pattern is prepending DEPRECATED_
to the entry name.