From 48a9b510b103c0554e5bbc84768b462d3cdda0ac Mon Sep 17 00:00:00 2001 From: "data-plane-api(CircleCI)" Date: Mon, 14 Jan 2019 01:21:58 +0000 Subject: [PATCH] api style: repeated field guidance (#5589) Signed-off-by: Matt Klein Mirrored from https://github.com/envoyproxy/envoy @ 74ef1a9030c0179412a6938439896a18cc81bf74 --- STYLE.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/STYLE.md b/STYLE.md index 9f938506..87da031c 100644 --- a/STYLE.md +++ b/STYLE.md @@ -71,6 +71,16 @@ In addition, the following conventions should be followed: * Always use plural field names for `repeated` fields, such as `filters`. +* Due to the fact that we consider JSON/YAML to be first class inputs, we cannot easily change a + a singular field to a repeated field (both due to JSON/YAML array structural differences as well + as singular vs. plural field naming). If there is a reasonable expectation that a field may need + to be repeated in the future, but we don't need it to be repeated right away, consider making it + repeated now but using constraints to enforce a maximum repeated size of 1. E.g.: + + ```proto + repeated OutputSink sinks = 1 [(validate.rules).repeated = {min_items: 1, max_items: 1}]; + ``` + * Always use upper camel case names for message types and enum types without embedded acronyms, such as `HttpRequest`.