From c3213abe37117df99c755a5d097e610aab2b89ab Mon Sep 17 00:00:00 2001 From: Edwin Buck Date: Sat, 3 Jun 2023 09:55:35 -0700 Subject: [PATCH 1/8] Initial submission of Helm Chart key naming conventions. Closes #329 Signed-off-by: Edwin Buck --- project/conventions.md | 108 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 108 insertions(+) create mode 100644 project/conventions.md diff --git a/project/conventions.md b/project/conventions.md new file mode 100644 index 0000000..d1aa33c --- /dev/null +++ b/project/conventions.md @@ -0,0 +1,108 @@ + +# Development Conventions + +This document intends to capture the current coding conventions for +the SPIRE Helm Chart project, permitting multiple developers to align +to a similar style and standard when offering their contributions. + +It is impossible to describe every scenario a developer might encounter, +likewise it is equally impossible to describe the best choice to make +under all future circumstances. For this reason, many conventions also +have a small explanation of the rationale behind the guidance, allowing +future development efforts to weigh and balance the conflicting forces +in ambiguous situations not clearly covered. + +This document is intended to be a living document. If you have an issue +with a convention, we hope that you will create an issue describing the +problem, and a pull request suggesting the update. By addressing the +convention, we hope to avoid arguments about conventions in the pull +request review process, which slow the process and are often subject to +the popular whims of the moment. + +## Conventions used in this document + +While this is not a software specification, the key words "MUST", +"MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", +"RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be +interpreted as closely to the convention as it would be to a +specification described in RFC 2119. + +Use of the word in its non-all caps form SHOULD NOT be interpreted in +the strict definitions user RFC 2119, but SHOULD be interpreted in +context with a meaning aligned to RFC 2119. + +## Helm Chart conventions + +Helm values are organized in a tree structure, with each entry having +a key, the path within the structure, and a value, the contents held +at that path. Some of the contents include objects and arrays, which +are structures that permit multiple values under a particular path. + +This design choice mimics the representation of a file system, and we +may use file system analogies to describe the conventions and choices +in the project. + +### Preference for absolute paths in templates + +Outside of looping constructs that require relative paths, templates +should use absolute paths (paths starting with the `.` character) for +their value references. + +### Helm Key path elements + +Elements refer to items in the configuration. Some of those items are +external to the project, while others are components the project choose +to implement the Helm Chart packaging solution. + +### Preferred characters for helm path elements + +Elements within a helm chart path SHOULD limit the use of special +characters, even when such characters are supported by Helm. ASCII +letters, upper and lower case, ASCII numerals, and the ASCII underscore +character are always permitted. + +Other characters, such as `@`, `~`, `-`, `&`, `+` are often used as +shorthand to represent, respectively `at`, `similar / not`, +`minus / without`, `and / reference`, `plus / with`. Helm key elements +MUST NOT contain such symbols, as it burdens the reader to deduce the +intent of the writer. + +### Camel Case for created elements. +Elements that refer to components that the project has created should +exclusively use camel case, with a the first word being lower case. To +illustrate, a "card sort order" path element would read "cardsharper". + +### Acronyms and Minimalists + +Occasionally the use of an Acronym or Minimalist is used as part of an +element name. An acronym is the use of the first letter of a phrase +or multi-word proper name that is pronounceable, while an initialisim is +the use of the first letter of a phrase or multi-word proper name +pronounced by naming the letters. `NASA` is an example of an acronym, +while `NFL` is an example of an Initialisim. + +To keep the recognition of the Acronym or Initialisim, an all capital +representation of the Acronym or Initialisim MUST be maintained. To +reduce the confusion this can create in camel case elements, we recommend +that such Acronyms and Initialisim be placed at the end of the element +or the element is restructured to avoid confusion. For example, +`mailingListNASA` or `mailingList.NASA` is preferred over +`NASAMailingList`. + +Acronyms and Initialisim occasionally use periods in their presentation. +When they do, the periods MUST be removed without replacement by +another character. To illustrate `U.S.S.R.` should be written as +`USSR`. + +### Abbreviations + +Abbreviations shorten words by using some of the letters of the original +word. In all cases, element names that contain parts which are +abbreviations should be represented in the case determined by the part's +position. For example, a Junior administrator, should be written as +`jrAdmin`. + +Abbreviations occasionally use periods in their presentation. When they +do, the periods MUST be removed without replacement by another character. +To illustrate, use `acctSchedule` for Acct. Schedule. From c4d19db98dc3cc2c777b9412f5999617c3d6d4c0 Mon Sep 17 00:00:00 2001 From: Edwin Buck Date: Wed, 7 Jun 2023 14:33:00 -0500 Subject: [PATCH 2/8] Update project/conventions.md Co-authored-by: Faisal Memon Signed-off-by: Edwin Buck --- project/conventions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/project/conventions.md b/project/conventions.md index d1aa33c..df2b7bf 100644 --- a/project/conventions.md +++ b/project/conventions.md @@ -71,7 +71,7 @@ intent of the writer. ### Camel Case for created elements. Elements that refer to components that the project has created should exclusively use camel case, with a the first word being lower case. To -illustrate, a "card sort order" path element would read "cardsharper". +illustrate, a "card sort order" path element would read "cardSortOrder". ### Acronyms and Minimalists From f6a7b62d9831e33cc02bad7aca6b6e4194e5b836 Mon Sep 17 00:00:00 2001 From: Edwin Buck Date: Wed, 7 Jun 2023 14:36:59 -0500 Subject: [PATCH 3/8] Update project/conventions.md Co-authored-by: Marco Franssen Signed-off-by: Edwin Buck --- project/conventions.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/project/conventions.md b/project/conventions.md index df2b7bf..646fa73 100644 --- a/project/conventions.md +++ b/project/conventions.md @@ -68,7 +68,8 @@ shorthand to represent, respectively `at`, `similar / not`, MUST NOT contain such symbols, as it burdens the reader to deduce the intent of the writer. -### Camel Case for created elements. +### Camel Case for created elements + Elements that refer to components that the project has created should exclusively use camel case, with a the first word being lower case. To illustrate, a "card sort order" path element would read "cardSortOrder". From d60d68c131a5782952931ad3e0a5d161fd5ab4f6 Mon Sep 17 00:00:00 2001 From: Edwin Buck Date: Thu, 8 Jun 2023 06:54:49 -0700 Subject: [PATCH 4/8] Added accidentally clipped explicit name guidelines. Signed-off-by: Edwin Buck --- project/conventions.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/project/conventions.md b/project/conventions.md index 646fa73..05ad512 100644 --- a/project/conventions.md +++ b/project/conventions.md @@ -74,6 +74,17 @@ Elements that refer to components that the project has created should exclusively use camel case, with a the first word being lower case. To illustrate, a "card sort order" path element would read "cardSortOrder". +### Exact Case for non-created elements + +Elements that reflect components that have well known names should make +every effort to use the well known name exactly, even if the rules for +captialization don't follow other naming conventions. Exceptions to +this SHOULD include replacing problematic characters with underscores, +to improve template functionality. To illustrate, the operating system +NeXTSTEP would read as "NeXTSTEP" and "NeXT Computers" SHOULD be written +as "NeXT_Computers" but may also be written as "NeXTComputers" if clarity +is maintained. + ### Acronyms and Minimalists Occasionally the use of an Acronym or Minimalist is used as part of an From 28e2abf7627ba5a658e9b218b0d205ed87bb8c6f Mon Sep 17 00:00:00 2001 From: Edwin Buck Date: Thu, 8 Jun 2023 07:00:12 -0700 Subject: [PATCH 5/8] Choose a different example for dotted Acronyms. Signed-off-by: Edwin Buck --- project/conventions.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/project/conventions.md b/project/conventions.md index 05ad512..7d4b187 100644 --- a/project/conventions.md +++ b/project/conventions.md @@ -104,8 +104,8 @@ or the element is restructured to avoid confusion. For example, Acronyms and Initialisim occasionally use periods in their presentation. When they do, the periods MUST be removed without replacement by -another character. To illustrate `U.S.S.R.` should be written as -`USSR`. +another character. To illustrate `U.N.` for the United Nations should +be written as `UN`. ### Abbreviations From cb182558153c59517da07596c87c639d22d3dba3 Mon Sep 17 00:00:00 2001 From: Edwin Buck Date: Fri, 9 Jun 2023 11:07:51 -0500 Subject: [PATCH 6/8] Update project/conventions.md Co-authored-by: kfox1111 Signed-off-by: Edwin Buck --- project/conventions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/project/conventions.md b/project/conventions.md index 7d4b187..126d275 100644 --- a/project/conventions.md +++ b/project/conventions.md @@ -62,7 +62,7 @@ characters, even when such characters are supported by Helm. ASCII letters, upper and lower case, ASCII numerals, and the ASCII underscore character are always permitted. -Other characters, such as `@`, `~`, `-`, `&`, `+` are often used as +Other characters, such as `@`, `~`, `&`, `+` are often used as shorthand to represent, respectively `at`, `similar / not`, `minus / without`, `and / reference`, `plus / with`. Helm key elements MUST NOT contain such symbols, as it burdens the reader to deduce the From 0cae9ce7c7ca9bb024e43e4c231afdcbc63fa166 Mon Sep 17 00:00:00 2001 From: Edwin Buck Date: Fri, 9 Jun 2023 11:08:10 -0500 Subject: [PATCH 7/8] Update project/conventions.md Co-authored-by: kfox1111 Signed-off-by: Edwin Buck --- project/conventions.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/project/conventions.md b/project/conventions.md index 126d275..65b8979 100644 --- a/project/conventions.md +++ b/project/conventions.md @@ -68,6 +68,8 @@ shorthand to represent, respectively `at`, `similar / not`, MUST NOT contain such symbols, as it burdens the reader to deduce the intent of the writer. +`-` SHOULD NOT be used when there are good alternatives. Its reasonable to use when spire itself uses it for config such as plugin names or required by helm for child charts. + ### Camel Case for created elements Elements that refer to components that the project has created should From ddc0166689f35e48bd48d140a96c358592938bf4 Mon Sep 17 00:00:00 2001 From: Edwin Buck Date: Fri, 9 Jun 2023 11:47:11 -0500 Subject: [PATCH 8/8] Fix line wrapping. Signed-off-by: Edwin Buck --- project/conventions.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/project/conventions.md b/project/conventions.md index 65b8979..6fe195b 100644 --- a/project/conventions.md +++ b/project/conventions.md @@ -68,7 +68,9 @@ shorthand to represent, respectively `at`, `similar / not`, MUST NOT contain such symbols, as it burdens the reader to deduce the intent of the writer. -`-` SHOULD NOT be used when there are good alternatives. Its reasonable to use when spire itself uses it for config such as plugin names or required by helm for child charts. +`-` SHOULD NOT be used when there are good alternatives. Its reasonable +to use when spire itself uses it for config such as plugin names or +required by helm for child charts. ### Camel Case for created elements