From b5dba5b4dad45ae60cef7dcdaeb589860154dd21 Mon Sep 17 00:00:00 2001 From: Prachi Pendse Date: Fri, 13 Dec 2019 16:43:50 -0800 Subject: [PATCH] Clarify removing annotation in config-io --- cmd/config/docs/api-conventions/config-io.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/cmd/config/docs/api-conventions/config-io.md b/cmd/config/docs/api-conventions/config-io.md index 777889a70..44337b4f4 100644 --- a/cmd/config/docs/api-conventions/config-io.md +++ b/cmd/config/docs/api-conventions/config-io.md @@ -4,16 +4,17 @@ Resource Configuration may be read / written from / to sources such as directori stdin|out or network. Tools may be composed using pipes such that the tools writing Resource Configuration may be a different tool from the one that read the configuration. In order for tools to be composed in this way, while preserving origin information -- -such as the original file, index, etc. +such as the original file, index, etc.: -Tools **SHOULD** write the following annotations when reading from sources, -and **SHOULD** respect the annotations when writing to sinks. +Tools **SHOULD** insert the following annotations when reading from sources, +and **SHOULD** delete the annotations when writing to sinks. ### `config.kubernetes.io/path` Records the slash-delimited, OS-agnostic, relative file path to a Resource. This annotation **SHOULD** be set when reading Resources from files. +It **SHOULD** be unset when writing Resources to files. When writing Resources to a directory, the Resource **SHOULD** be written to the corresponding path relative to that directory. @@ -27,10 +28,11 @@ metadata: ### `config.kubernetes.io/index` -Records the index of a Resource in file. In a multi-object files YAML file, Resources are separated +Records the index of a Resource in file. In a multi-object YAML file, Resources are separated by three dashes (`---`), and the index represents the positon of the Resource starting from zero. This annotation **SHOULD** be set when reading Resources from files. +It **SHOULD** be unset when writing Resources to files. When writing multiple Resources to the same file, the Resource **SHOULD** be written in the relative order matching the index.