Document naming conventions & Naming alignment (#368)

Contributed on behalf of STMicroelectronics

Co-authored-by: Simon Graband <[email protected]>
Co-authored-by: Lucas Koehler <[email protected]>

README.md

@@ -100,9 +100,9 @@ helm repo update
 ```bash
 helm install theia-cloud-base theia-cloud-remote/theia-cloud-base --set [email protected]
 
-helm install theia-cloud-crds theia-cloud-remote/theia-cloud-crds  --namespace theiacloud --create-namespace
+helm install theia-cloud-crds theia-cloud-remote/theia-cloud-crds  --namespace theia-cloud --create-namespace
 
-helm install theia-cloud theia-cloud-remote/theia-cloud --namespace theiacloud
+helm install theia-cloud theia-cloud-remote/theia-cloud --namespace theia-cloud
 ```
 
 ### Install the current next version
@@ -112,21 +112,21 @@ Simply add the `--devel` flag:
 ```bash
 helm install theia-cloud-base theia-cloud-remote/theia-cloud-base --set [email protected] --devel
 
-helm install theia-cloud-crds theia-cloud-remote/theia-cloud-crds  --namespace theiacloud --create-namespace --devel
+helm install theia-cloud-crds theia-cloud-remote/theia-cloud-crds  --namespace theia-cloud --create-namespace --devel
 
-helm install theia-cloud theia-cloud-remote/theia-cloud --namespace theiacloud --devel
+helm install theia-cloud theia-cloud-remote/theia-cloud --namespace theia-cloud --devel
 ```
 
 ### Optional: switch to the newly created namespace
 
 ```bash
-kubectl config set-context --current --namespace=theiacloud
+kubectl config set-context --current --namespace=theia-cloud
 ```
 
 ### Uninstall
 
 ```bash
-helm uninstall theia-cloud -n theiacloud
+helm uninstall theia-cloud -n theia-cloud
 ```
 
 ### Getting started with

demo/dockerfiles/demo-theia-monitor-vscode/Dockerfile

@@ -2,8 +2,8 @@ FROM node:18-bullseye-slim as build-stage
 
 # Copy and unzip the vsix file
 RUN apt-get update && apt-get install -y unzip && rm -rf /var/lib/apt/lists/*
-COPY theiacloud-monitor-0.12.0-next.vsix /tmp/theiacloud-monitor.vsix
-RUN mkdir /tmp/extracted && unzip /tmp/theiacloud-monitor.vsix -d /tmp/extracted
+COPY theia-cloud-monitor-0.12.0-next.vsix /tmp/theia-cloud-monitor.vsix
+RUN mkdir /tmp/extracted && unzip /tmp/theia-cloud-monitor.vsix -d /tmp/extracted
 
 FROM theiacloud/theia-cloud-demo:0.12.0-next as production-stage
 

documentation/Architecture.md

@@ -2,7 +2,7 @@
 
 The Theia Cloud Operator listens for changes to custom resources inside the cluster. With those custom resources clients may trigger the creation/deletion/handling of workspaces and sessions. The Operator is responsible for handling all things that are related to the Kubernetes-Resources for workspaces and sessions. All access is authenticated via an Authenticator.
 
-![Theia Cloud Diagram](theiacloud.png "Theia Cloud")
+![Theia Cloud Diagram](theia-cloud.png "Theia Cloud")
 
 ## Operator Java Overview
 

documentation/Install.md

@@ -76,9 +76,9 @@ helm repo update
 ```bash
 helm install theia-cloud-base theia-cloud-remote/theia-cloud-base --set [email protected]
 
-helm install theia-cloud-crds theia-cloud-remote/theia-cloud-crds  --namespace theiacloud --create-namespace
+helm install theia-cloud-crds theia-cloud-remote/theia-cloud-crds  --namespace theia-cloud --create-namespace
 
-helm install theia-cloud theia-cloud-remote/theia-cloud --namespace theiacloud
+helm install theia-cloud theia-cloud-remote/theia-cloud --namespace theia-cloud
 ```
 
 ### Install the current next version
@@ -88,31 +88,31 @@ Simply add the `--devel` flag:
 ```bash
 helm install theia-cloud-base theia-cloud-remote/theia-cloud-base --set [email protected] --devel
 
-helm install theia-cloud-crds theia-cloud-remote/theia-cloud-crds  --namespace theiacloud --create-namespace --devel
+helm install theia-cloud-crds theia-cloud-remote/theia-cloud-crds  --namespace theia-cloud --create-namespace --devel
 
-helm install theia-cloud theia-cloud-remote/theia-cloud --namespace theiacloud --devel
+helm install theia-cloud theia-cloud-remote/theia-cloud --namespace theia-cloud --devel
 ```
 
 ### Optional: switch to the newly created namespace
 
 ```bash
-kubectl config set-context --current --namespace=theiacloud
+kubectl config set-context --current --namespace=theia-cloud
 ```
 
 ### Trouble shooting
 
 Recreate tls secret for sessions:
 
-`kubectl delete secret ws-cert-secret -n theiacloud`
+`kubectl delete secret ws-cert-secret -n theia-cloud`
 
 ## Check
 
 ```bash
-helm get manifest theia-cloud -n theiacloud
+helm get manifest theia-cloud -n theia-cloud
 ```
 
 ## Uninstall
 
 ```bash
-helm uninstall theia-cloud -n theiacloud
+helm uninstall theia-cloud -n theia-cloud
 ```

documentation/Naming.md

@@ -0,0 +1,48 @@
+# Naming Conventions
+
+The project name is **Theia Cloud** (with a space), which is a subproject of Eclipse Theia.
+
+Since various languages and use cases follow different naming conventions, we aim to align with these conventions as closely as possible.
+
+Below are guidelines for commonly used naming conventions specific to this project.
+
+## `theia.cloud`
+
+Use `theia.cloud` in hierarchical structures and identifiers. Examples include:
+
+- **Java package/jar names**: `org.eclipse.theia.cloud`
+- **Java system properties**: `-Dtheia.cloud.app.id=yourAppId`
+- **Kubernetes group names/metadata**: `theia.cloud`, `theia.cloud/v1beta9`, `sessions.theia.cloud`
+- **Theia command identifiers**: `theia.cloud.monitor.activity.report`
+
+## `TheiaCloud` / `theiaCloud`
+
+Use **PascalCase** or **camelCase** for Java/TypeScript class, method, and property names, such as `DefaultTheiaCloudOperatorLauncher` or `window.theiaCloudConfig`.
+
+This format is also appropriate in contexts where spaces are avoided for technical reasons, such as in **Keycloak Realm** names (e.g., `TheiaCloud`).
+
+## `theia-cloud`
+
+This format serves as a preferred technical abbreviation. Use it when no other conventions apply, including:
+
+- **NPM Package names**
+- **File names**
+- **k8s namespaces**
+
+## `THEIACLOUD`
+
+Use **all uppercase** with underscores for **environment variables**, such as `THEIACLOUD_SESSION_NAME`.
+
+We can't use `THEIA_CLOUD` because `THEIA_` env variables may get special treatment by Theia itself.
+
+## Theia Cloud
+
+In general documentation and free text, use the standard project name **Theia Cloud** (with a space). Avoid spaces in technical contexts.
+
+## `theia-cloud.io`
+
+For **Kubernetes labels**, use the project domain as a prefix to custom labels, such as `theia-cloud.io/workspace-name`.
+
+## Avoid `theiacloud` in Code
+
+Avoid using the project name without separators or spaces, especially without PascalCase or camelCase. This format is reserved for usernames, such as those on Docker or npm.

documentation/operator.graphml

@@ -21,7 +21,7 @@
           <y:Geometry height="28.0" width="100.0" x="1157.0" y="186.0"/>
           <y:Fill color="#FFCC00" transparent="false"/>
           <y:BorderStyle color="#000000" type="line" width="1.0"/>
-          <y:NodeLabel alignment="center" autoSizePolicy="content" fontFamily="Dialog" fontSize="13" fontStyle="bold" hasBackgroundColor="false" hasLineColor="false" height="19.1328125" horizontalTextPosition="center" iconTextGap="4" modelName="custom" textColor="#000000" verticalTextPosition="bottom" visible="true" width="85.65625" x="7.171875" xml:space="preserve" y="3.0">TheiaCloud<y:LabelModel><y:SmartNodeLabelModel distance="4.0"/></y:LabelModel><y:ModelParameter><y:SmartNodeLabelModelParameter labelRatioX="0.0" labelRatioY="0.0" nodeRatioX="0.0" nodeRatioY="0.0" offsetX="0.0" offsetY="0.0" upX="0.0" upY="-1.0"/></y:ModelParameter></y:NodeLabel>
+          <y:NodeLabel alignment="center" autoSizePolicy="content" fontFamily="Dialog" fontSize="13" fontStyle="bold" hasBackgroundColor="false" hasLineColor="false" height="19.1328125" horizontalTextPosition="center" iconTextGap="4" modelName="custom" textColor="#000000" verticalTextPosition="bottom" visible="true" width="90.18212890625" x="4.908935546875" xml:space="preserve" y="3.0">Theia Cloud<y:LabelModel><y:SmartNodeLabelModel distance="4.0"/></y:LabelModel><y:ModelParameter><y:SmartNodeLabelModelParameter labelRatioX="0.0" labelRatioY="0.0" nodeRatioX="0.0" nodeRatioY="0.0" offsetX="0.0" offsetY="0.0" upX="0.0" upY="-1.0"/></y:ModelParameter></y:NodeLabel>
           <y:UML clipContent="true" constraint="" hasDetailsColor="false" omitDetails="false" stereotype="" use3DEffect="true">
             <y:AttributeLabel xml:space="preserve"/>
             <y:MethodLabel xml:space="preserve"/>
@@ -67,7 +67,7 @@ AppDefinitionAddedHandler<y:LabelModel><y:SmartNodeLabelModel distance="4.0"/></
           <y:Geometry height="43.0" width="203.0" x="848.5" y="339.0"/>
           <y:Fill color="#FFCC00" transparent="false"/>
           <y:BorderStyle color="#000000" type="line" width="1.0"/>
-          <y:NodeLabel alignment="center" autoSizePolicy="content" fontFamily="Dialog" fontSize="13" fontStyle="bold" hasBackgroundColor="false" hasLineColor="false" height="34.265625" horizontalTextPosition="center" iconTextGap="4" modelName="custom" textColor="#000000" verticalTextPosition="bottom" visible="true" width="189.35791015625" x="6.821044921875" xml:space="preserve" y="3.0">&lt;&lt;interface&gt;&gt;
+          <y:NodeLabel alignment="center" autoSizePolicy="content" fontFamily="Dialog" fontSize="13" fontStyle="bold" hasBackgroundColor="false" hasLineColor="false" height="34.265625" horizontalTextPosition="center" iconTextGap="4" modelName="custom" textColor="#000000" verticalTextPosition="bottom" visible="true" width="164.9892578125" x="19.00537109375" xml:space="preserve" y="3.0">&lt;&lt;interface&gt;&gt;
 SessionAddedHandler<y:LabelModel><y:SmartNodeLabelModel distance="4.0"/></y:LabelModel><y:ModelParameter><y:SmartNodeLabelModelParameter labelRatioX="0.0" labelRatioY="0.0" nodeRatioX="0.0" nodeRatioY="0.0" offsetX="0.0" offsetY="0.0" upX="0.0" upY="-1.0"/></y:ModelParameter></y:NodeLabel>
           <y:UML clipContent="true" constraint="" hasDetailsColor="false" omitDetails="false" stereotype="" use3DEffect="true">
             <y:AttributeLabel xml:space="preserve"/>
@@ -98,7 +98,7 @@ SessionAddedHandler<y:LabelModel><y:SmartNodeLabelModel distance="4.0"/></y:Labe
           <y:Geometry height="28.0" width="279.0" x="1217.0" y="601.0"/>
           <y:Fill color="#FFCC00" transparent="false"/>
           <y:BorderStyle color="#000000" type="line" width="1.0"/>
-          <y:NodeLabel alignment="center" autoSizePolicy="content" fontFamily="Dialog" fontSize="13" fontStyle="bold" hasBackgroundColor="false" hasLineColor="false" height="19.1328125" horizontalTextPosition="center" iconTextGap="4" modelName="custom" textColor="#000000" verticalTextPosition="bottom" visible="true" width="259.4296875" x="9.78515625" xml:space="preserve" y="3.0">LazyStartSessionAddedHandler<y:LabelModel><y:SmartNodeLabelModel distance="4.0"/></y:LabelModel><y:ModelParameter><y:SmartNodeLabelModelParameter labelRatioX="0.0" labelRatioY="0.0" nodeRatioX="0.0" nodeRatioY="0.0" offsetX="0.0" offsetY="0.0" upX="0.0" upY="-1.0"/></y:ModelParameter></y:NodeLabel>
+          <y:NodeLabel alignment="center" autoSizePolicy="content" fontFamily="Dialog" fontSize="13" fontStyle="bold" hasBackgroundColor="false" hasLineColor="false" height="19.1328125" horizontalTextPosition="center" iconTextGap="4" modelName="custom" textColor="#000000" verticalTextPosition="bottom" visible="true" width="235.06103515625" x="21.969482421875" xml:space="preserve" y="3.0">LazyStartSessionAddedHandler<y:LabelModel><y:SmartNodeLabelModel distance="4.0"/></y:LabelModel><y:ModelParameter><y:SmartNodeLabelModelParameter labelRatioX="0.0" labelRatioY="0.0" nodeRatioX="0.0" nodeRatioY="0.0" offsetX="0.0" offsetY="0.0" upX="0.0" upY="-1.0"/></y:ModelParameter></y:NodeLabel>
           <y:UML clipContent="true" constraint="" hasDetailsColor="false" omitDetails="false" stereotype="" use3DEffect="true">
             <y:AttributeLabel xml:space="preserve"/>
             <y:MethodLabel xml:space="preserve"/>
@@ -113,7 +113,7 @@ SessionAddedHandler<y:LabelModel><y:SmartNodeLabelModel distance="4.0"/></y:Labe
           <y:Geometry height="28.0" width="279.0" x="699.0" y="638.0"/>
           <y:Fill color="#FFCC00" transparent="false"/>
           <y:BorderStyle color="#000000" type="line" width="1.0"/>
-          <y:NodeLabel alignment="center" autoSizePolicy="content" fontFamily="Dialog" fontSize="13" fontStyle="bold" hasBackgroundColor="false" hasLineColor="false" height="19.1328125" horizontalTextPosition="center" iconTextGap="4" modelName="custom" textColor="#000000" verticalTextPosition="bottom" visible="true" width="268.51953125" x="5.240234375" xml:space="preserve" y="3.0">EagerStartSessionAddedHandler<y:LabelModel><y:SmartNodeLabelModel distance="4.0"/></y:LabelModel><y:ModelParameter><y:SmartNodeLabelModelParameter labelRatioX="0.0" labelRatioY="0.0" nodeRatioX="0.0" nodeRatioY="0.0" offsetX="0.0" offsetY="0.0" upX="0.0" upY="-1.0"/></y:ModelParameter></y:NodeLabel>
+          <y:NodeLabel alignment="center" autoSizePolicy="content" fontFamily="Dialog" fontSize="13" fontStyle="bold" hasBackgroundColor="false" hasLineColor="false" height="19.1328125" horizontalTextPosition="center" iconTextGap="4" modelName="custom" textColor="#000000" verticalTextPosition="bottom" visible="true" width="244.15087890625" x="17.424560546875" xml:space="preserve" y="3.0">EagerStartSessionAddedHandler<y:LabelModel><y:SmartNodeLabelModel distance="4.0"/></y:LabelModel><y:ModelParameter><y:SmartNodeLabelModelParameter labelRatioX="0.0" labelRatioY="0.0" nodeRatioX="0.0" nodeRatioY="0.0" offsetX="0.0" offsetY="0.0" upX="0.0" upY="-1.0"/></y:ModelParameter></y:NodeLabel>
           <y:UML clipContent="true" constraint="" hasDetailsColor="false" omitDetails="false" stereotype="" use3DEffect="true">
             <y:AttributeLabel xml:space="preserve"/>
             <y:MethodLabel xml:space="preserve"/>
@@ -143,7 +143,7 @@ SessionAddedHandler<y:LabelModel><y:SmartNodeLabelModel distance="4.0"/></y:Labe
           <y:Geometry height="86.0" width="854.0" x="654.0" y="707.0"/>
           <y:Fill color="#CCFFFF" transparent="false"/>
           <y:BorderStyle color="#000000" type="line" width="1.0"/>
-          <y:NodeLabel alignment="center" autoSizePolicy="content" fontFamily="Dialog" fontSize="12" fontStyle="plain" hasBackgroundColor="false" hasLineColor="false" height="73.84375" horizontalTextPosition="center" iconTextGap="4" modelName="custom" textColor="#000000" verticalTextPosition="bottom" visible="true" width="846.208984375" x="4.0" xml:space="preserve" y="4.0">We may have different kinds of implementations of the handlers. 
+          <y:NodeLabel alignment="center" autoSizePolicy="content" fontFamily="Dialog" fontSize="12" fontStyle="plain" hasBackgroundColor="false" hasLineColor="false" height="73.84375" horizontalTextPosition="center" iconTextGap="4" modelName="custom" textColor="#000000" verticalTextPosition="bottom" visible="true" width="826.38671875" x="4.0" xml:space="preserve" y="4.0">We may have different kinds of implementations of the handlers. 
 E.g. we might have handlers that start up unassigned pods already and assign the running pods to a user on session added (EagerStart)
 Or we could do it Che-like and spin up the pod when a new session is added
 
@@ -174,7 +174,7 @@ IngressCreationService<y:LabelModel><y:SmartNodeLabelModel distance="4.0"/></y:L
           <y:Geometry height="81.0" width="310.0" x="1375.0" y="159.5"/>
           <y:Fill color="#FFCC00" transparent="false"/>
           <y:BorderStyle color="#000000" type="line" width="1.0"/>
-          <y:NodeLabel alignment="center" autoSizePolicy="content" fontFamily="Dialog" fontSize="13" fontStyle="plain" hasBackgroundColor="false" hasLineColor="false" height="34.265625" horizontalTextPosition="center" iconTextGap="4" modelName="custom" textColor="#000000" verticalTextPosition="bottom" visible="true" width="298.3916015625" x="5.80419921875" xml:space="preserve" y="23.3671875">Listens for app definition/sessions changes
+          <y:NodeLabel alignment="center" autoSizePolicy="content" fontFamily="Dialog" fontSize="13" fontStyle="plain" hasBackgroundColor="false" hasLineColor="false" height="34.265625" horizontalTextPosition="center" iconTextGap="4" modelName="custom" textColor="#000000" verticalTextPosition="bottom" visible="true" width="283.6904296875" x="13.15478515625" xml:space="preserve" y="23.3671875">Listens for app definition/sessions changes
 and delegates to handlers<y:LabelModel><y:SmartNodeLabelModel distance="4.0"/></y:LabelModel><y:ModelParameter><y:SmartNodeLabelModelParameter labelRatioX="0.0" labelRatioY="0.0" nodeRatioX="0.0" nodeRatioY="0.0" offsetX="0.0" offsetY="0.0" upX="0.0" upY="-1.0"/></y:ModelParameter></y:NodeLabel>
           <y:Shape type="ellipse"/>
         </y:ShapeNode>

java/operator/README.md

@@ -36,7 +36,7 @@ To debug the Default Theia Cloud Operator, follow these steps:
      minikube ip
 ```
 
-_Note_: Ensure your local `kubectl` is set to the correct namespace (e.g., `theiacloud`), as the debuggable operator will interact with your local Kubernetes cluster.
+_Note_: Ensure your local `kubectl` is set to the correct namespace (e.g., `theia-cloud`), as the debuggable operator will interact with your local Kubernetes cluster.
 
 ### Theia Cloud Operator Library
 

java/operator/org.eclipse.theia.cloud.operator/src/main/java/org/eclipse/theia/cloud/operator/handler/appdef/EagerStartAppDefinitionAddedHandler.java

@@ -57,7 +57,7 @@ public class EagerStartAppDefinitionAddedHandler implements AppDefinitionHandler
 
     private static final Logger LOGGER = LogManager.getLogger(EagerStartAppDefinitionAddedHandler.class);
 
-    public static final String LABEL_KEY = "theiacloud";
+    public static final String LABEL_KEY = "theia-cloud.io/template-purpose";
     public static final String LABEL_VALUE_PROXY = "proxy";
     public static final String LABEL_VALUE_EMAILS = "emails";
 

java/operator/org.eclipse.theia.cloud.operator/src/main/resources/templateConfigmap.yaml

@@ -3,7 +3,7 @@ kind: ConfigMap
 metadata:
   name: placeholder-configname
   labels:
-    theiacloud: proxy
+    theia-cloud.io/template-purpose: proxy
   namespace: placeholder-namespace
   ownerReferences:
     - apiVersion: theia.cloud/v1beta9

java/operator/org.eclipse.theia.cloud.operator/src/main/resources/templateConfigmapEmails.yaml

@@ -3,7 +3,7 @@ kind: ConfigMap
 metadata:
   name: placeholder-emailsconfigname
   labels:
-    theiacloud: emails
+    theia-cloud.io/template-purpose: emails
   namespace: placeholder-namespace
   ownerReferences:
     - apiVersion: theia.cloud/v1beta9

java/operator/org.eclipse.theia.cloud.operator/src/main/resources/templatePersistentVolumeClaim.yaml

@@ -4,7 +4,7 @@ metadata:
   name: placeholder-pv
   namespace: placeholder-namespace
   labels:
-    theia.cloud.workspace.name: placeholder-label-workspace-name
+    theia-cloud.io/workspace-name: placeholder-label-workspace-name
 spec:
   accessModes:
     - ReadWriteOnce

java/operator/org.eclipse.theia.cloud.operator/src/main/resources/templatePersistentVolumeClaimMinikube.yaml

@@ -4,7 +4,7 @@ metadata:
   name: placeholder-pv
   namespace: placeholder-namespace
   labels:
-    theia.cloud.workspace.name: placeholder-label-workspace-name
+    theia-cloud.io/workspace-name: placeholder-label-workspace-name
 spec:
   accessModes:
     - ReadWriteOnce

java/service/org.eclipse.theia.cloud.service/README.md

@@ -74,8 +74,6 @@ Easily start your RESTful Web Services
 
 Unit tests use the Quarkus test infrastructure.
 
-All tests can be run in Eclipse via launch config [TheiaCloud Service Tests](./TheiaCloud Service Tests.launch).
-
 When running tests from an IDE, the following VM argument might need to be set to enable logging during tests (this is pre-configured in the launch config):
 
 ```bash

java/service/org.eclipse.theia.cloud.service/src/main/java/org/eclipse/theia/cloud/service/ApplicationProperties.java

@@ -25,8 +25,8 @@
 @ApplicationScoped
 public class ApplicationProperties {
 
-    private static final String THEIA_CLOUD_APP_ID = "theia.cloud.app.id";
-    private static final String THEIA_CLOUD_USE_KEYCLOAK = "theia.cloud.use.keycloak";
+    private static final String THEIACLOUD_APP_ID = "theia.cloud.app.id";
+    private static final String THEIACLOUD_USE_KEYCLOAK = "theia.cloud.use.keycloak";
 
     private final Logger logger;
 
@@ -35,9 +35,9 @@ public class ApplicationProperties {
 
     public ApplicationProperties() {
         logger = Logger.getLogger(getClass());
-        appId = System.getProperty(THEIA_CLOUD_APP_ID, "asdfghjkl");
+        appId = System.getProperty(THEIACLOUD_APP_ID, "asdfghjkl");
         // Only disable keycloak if the value was explicitly set to exactly "false".
-        useKeycloak = !"false".equals(System.getProperty(THEIA_CLOUD_USE_KEYCLOAK));
+        useKeycloak = !"false".equals(System.getProperty(THEIACLOUD_USE_KEYCLOAK));
         if (!useKeycloak) {
             logger.warn("Keycloak integration was disabled. Anonymous requests are allowed!");
         }