From 134578db2165b4b522013d0e7d6ac974f9e4e744 Mon Sep 17 00:00:00 2001 From: Jesse Szwedko Date: Fri, 2 Jun 2023 15:48:10 -0400 Subject: [PATCH] chore: Codify flag naming including sentinel values (#17569) Starting with `SHOULD` while we feel this out some more. Might change to `MUST` once we build up more confidence. Signed-off-by: Jesse Szwedko Signed-off-by: Jesse Szwedko --- docs/specs/configuration.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/docs/specs/configuration.md b/docs/specs/configuration.md index 7831f9389cb83..9e9a06e16760b 100644 --- a/docs/specs/configuration.md +++ b/docs/specs/configuration.md @@ -9,10 +9,12 @@ interpreted as described in [RFC 2119]. - [Introduction](#introduction) - [Scope](#scope) - [Terminology](#terminology) + - [Flag](#flag) - [Entity](#entity) - [Option](#option) - [Schema](#schema) - [Naming](#naming) + - [Flag naming](#flag-naming) - [Entity naming](#entity-naming) - [Option naming](#option-naming) - [Types](#types) @@ -37,6 +39,10 @@ relevant specifications, such as the [component specification]. ## Terminology +### Flag + +"Flag" refers to a CLI flag provided when running Vector. + ### Entity "Entity" refers to a Vector concept used to model Vector's processing graph. @@ -53,6 +59,16 @@ under entities and also used to define global Vector behavior. ### Naming +#### Flag naming + +- MUST only contain ASCII alphanumeric, lowercase, and hyphens +- MUST be in kebab-case format when multiple words are used (e.g., `config-dir`) +- For flags that take a value, but are also able to be "disabled", they SHOULD NOT use a sentinel + value. Instead they SHOULD have a second flag added prefixed with `no-` and SHOULD leave off any + unit suffixes. For example, to disable `--graceful-shutdown-limit-secs`, + a `--no-graceful-shutdown` flag was added. Vector MUST NOT allow both the flag and its negative to + be specified at the same time. + #### Entity naming - MUST only contain ASCII alphanumeric, lowercase, and underscores