Solving naming abiguity

[lindnerby]

In order to settle on one name when talking about certain domain entities in our project, we have to find our Ubiquitious Language, because software doesn't cope well with ambiguity.
Keep in mind that it is a good idea to choose a name that is also often used in spoken language by us and by other stakeholders! Which is the whole reason the concept of sitting together and defining a Ubiquitious Language came up in Domain Driven Design, so that when stakeholders talk about something, chances are high they are actually talking about the same thing!

Currently up for discussion:

1. Name for "everything related to our controlplane". In code we most often find, either as a prefix or a standalone param or var, also also path and folder names (examples in no particular order): kcpCrd, kcpClient, controlPlaneClient, cClient, KCPMODULESTATE, flagvar.InKcpMode, kcpEnvVar, controlplane_test, config/controlplane, controlPlaneEnv *envtest.Environment, ...
   Ignoring the the lazy c Prefix, the two candidates are:

   • kcp
   • controlPlane

2. Name for "everything related to a remote skr cluster". Examples, similar to above: skr_client_lookup. SKRWebhookManager, runtimeClient, pkg/remote, runtimeRESTConfig, CreateModuleTemplateCRDInRuntime, remoteClientCache, NewSKRCluster, SKRWebhookAnnotation, RemoteClusterLookup, ...
   Adding one name idea of our previous discussion (which is not being used in code at all yet), the four candidates to decide from are:

   • skr
   • remote
   • runtime
   • kymaRuntime

Please cast your vote in this discussion, so we can quickly find one name that is used, or at least preferred to be used, throughout our codebase (and meetings).

Also consider our glossary, that contains entity names of both domains:
https://github.com/kyma-project/lifecycle-manager/wiki/Glossary

[c-pius]

kcp

Would prefer either skr or kymaRuntime.

Reasoning

I mainly share the opinion that the terms should be as precise as possible and not leave room for ambiguity. controlPlane is a general concept (mostly associated with service mesh). remote and runtime could be anything.

skr or kymaRuntime: I think it is okay to go with either. Regarding s in skr I would not worry to much about it. After all it should be clear what it refers to. And if in doubt for OS, we can just claim it stands for supervised => supervised kyma runtime (in the OS case, one could even argue if the term runtime is a good fit, or if it should rather be cluster or something else). A justification for kcp + kymaRuntime could be that we just abbreviate terms consisting of three words or more.

[jeremyharisch]

I like your argumentation, but i guess we cannot just claim a different meaning behind a well established name in the org 😓

[amritanshusikdar]

I'd vote for:

1

kcp

2

skr

If I had to choose an alternative, then it'd be a controlPlane and kymaRuntime pair. Main reason being the code readability and it being more english-like. But when thinking from the practicality of it, it'd be easier to have the kcp and skr pair, solely because of the fact that its shorter, more concise and directly conveys the meaning, leaving no space for ambiguity. Moreover for people who are going through the codebase for the very first time, they can always go through the glossary in a couple of seconds to figure out their respective meanings/full-forms.

[Tomasz-Smelcerz-SAP]

• 1 kcp
• 2 skr

I know that these acronyms bear some "business" meanings that may be not valid - in some possible cases.
But at this moment they reflect 100% of our real use-cases, apart from testing environments. Am I missing anything?
If, in the future KLM will be used and deployed in some other environments, the appropriate naming will came along with these scenarios. Then we'll rename the identifiers in the code base. If they are specific enough, that is a simple task that can be easily automated using tools like sed or awk. Or an AI-powered IDE

[nesmabadr]

1. kcp
2. skr

I believe these are the most common terms that are used when we refer to either of them. Also, they are already defined in the documentation so by the time anyone gets into the code, they would have already figured out what these stand for from the docs.

[jeremyharisch]

1. kcp
2. kymaRuntime or skr

I think kcp is very suitable, since here we always talk about the control-plane environment who is in control of all related Kyma clusters. For the second, if personally would prefer kymaRuntime since it is more generic without the mentioning of SAP in the context (skr = SAP Kyma Runtime). But for the convenience of having short terms in the code, I am also fine with skr. But we then should have a section in our docs to explain it.

[LeelaChacha]

kcp and skr seem the best options to me. They are more short and precise. They leave no ambiguity.

My reasoning for not picking the runner-up kymaRuntime is that though kymaRuntime and SKR convey same meaning without ambiguity, KCP and SKR just belong together in a developer's mental space.