From 8199fdaa02cd438ad3e77057bf9ae0158de56a7a Mon Sep 17 00:00:00 2001 From: Jseph Date: Wed, 20 Dec 2023 15:32:34 -0800 Subject: [PATCH 1/4] Add guidance to avoid overly generic resource names. These often cause confusion down the line as the API introduces more concepts. --- aip/general/0123.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/aip/general/0123.md b/aip/general/0123.md index 70d9a3e599..a3d41f2e8c 100644 --- a/aip/general/0123.md +++ b/aip/general/0123.md @@ -42,6 +42,9 @@ the following pattern: `{Service Name}/{Type}`. The type name **must**: - Be of the singular form of the noun. - Use PascalCase (UpperCamelCase). +Additionally APIs **should** avoid avoid overly generic resource names like +Metadata, Resource, Config, Settings, etc. + ### Examples Examples of resource types include: From d852fa17930e8eda0c68888332349f3bc52643bf Mon Sep 17 00:00:00 2001 From: Jseph Date: Wed, 20 Dec 2023 15:38:36 -0800 Subject: [PATCH 2/4] Added update description Note: the date will need to be updated if this is merged. --- aip/general/0123.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/aip/general/0123.md b/aip/general/0123.md index a3d41f2e8c..907111686d 100644 --- a/aip/general/0123.md +++ b/aip/general/0123.md @@ -121,7 +121,7 @@ such as UpperCamelCase and snake_case. ## Changelog - +- **2023-12-20**: Added guidance on overly-generic resource type names. - **2023-09-19**: Prohibit duplicate pattern variables. - **2023-05-06**: Adding requirement of singular and plural. - **2023-01-28**: Clarifying guidance for the resource type name. From 67d1e36f48850268a5139795535fc01980768cb7 Mon Sep 17 00:00:00 2001 From: Jseph Date: Wed, 20 Dec 2023 15:47:43 -0800 Subject: [PATCH 3/4] Fix typo Fix Typo --- aip/general/0123.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/aip/general/0123.md b/aip/general/0123.md index 907111686d..b747986053 100644 --- a/aip/general/0123.md +++ b/aip/general/0123.md @@ -42,8 +42,8 @@ the following pattern: `{Service Name}/{Type}`. The type name **must**: - Be of the singular form of the noun. - Use PascalCase (UpperCamelCase). -Additionally APIs **should** avoid avoid overly generic resource names like -Metadata, Resource, Config, Settings, etc. +Additionally APIs **should** avoid overly generic resource names like Metadata, +Resource, Config, Settings, etc. ### Examples From fb4dce2ca56feaca11de0f7a9fc0ce4df38a083d Mon Sep 17 00:00:00 2001 From: Jseph Date: Wed, 20 Dec 2023 16:30:59 -0800 Subject: [PATCH 4/4] Add rationale and make suggested formatting changes --- aip/general/0123.md | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/aip/general/0123.md b/aip/general/0123.md index b747986053..c66e20093c 100644 --- a/aip/general/0123.md +++ b/aip/general/0123.md @@ -42,8 +42,8 @@ the following pattern: `{Service Name}/{Type}`. The type name **must**: - Be of the singular form of the noun. - Use PascalCase (UpperCamelCase). -Additionally APIs **should** avoid overly generic resource names like Metadata, -Resource, Config, Settings, etc. +Additionally APIs **should** avoid overly generic resource names like +`Metadata`, `Resource`, `Config`, `Settings`, etc. ### Examples @@ -111,6 +111,13 @@ proper name to use in code and documentation. lowerCamelCase can be translated into other common forms of a resource name such as UpperCamelCase and snake_case. +### Overly Generic Type Names + +Overly generic types like `Metadata` or `Resource` will cause confusion as the +API introduces more concepts. Unless the resource represents a +[singleton][aip-156] containing API-level settings, a more specific name should +be used. + [aip-122]: ./0122.md [API Group]: https://kubernetes.io/docs/concepts/overview/kubernetes-api/#api-groups