[INTERNAL] Document metadata.name restrictions

See SAP/ui5-project#552

docs/pages/Configuration.md

@@ -71,9 +71,23 @@ In addition, a project must define a `type`. This can be either `application`, `
 
 #### name
 
-A project must have a `name` and might define a `copyright` string.
+A project must have a `name`.
 
-In UI5 Tooling, a project is typically identified by the configured `name`. It must be unique and should ideally follow a namespace scheme like `company.businessarea.project`.
+In UI5 Tooling, a project is typically identified by the configured `name`. It must be unique and should ideally follow a namespace scheme like `organization.product.project` for UI5 projects or `ui5-task-heavy-boulder` for extension-projects.
+
+The `name` property of **projects defining Specification Version 3.0 and above** must satisfy the following conditions:
+
+* Must be at least 3 characters long
+* Must be no longer than 50 characters
+* Must contain lowercase characters only
+* Must contain alphanumeric characters, dash, underscore and period only
+    - Exception: `@` and `/` are allowed at certain positions as
+      explained below
+* Must start with an alphabetic character or an `@`-character
+* If it starts with an `@`-character, it must contain exactly one
+  forward-slash `/`
+    - This is aligned with the npm concept for package scopes
+    - e.g. `@org/lib.name`
 
 #### copyright
 
@@ -97,8 +111,7 @@ Note that all configured paths must be written in POSIX (i.e. using only forward
 === "Applications"
     - `webapp`: Mapped to runtime path `/` (root)
 
-    *Default configuration:*
-    ```yaml
+    ```yaml title="Default Configuration"
     resources:
       configuration:
         paths:
@@ -109,8 +122,7 @@ Note that all configured paths must be written in POSIX (i.e. using only forward
     - `src`: Mapped to runtime path `/resources`
     - `test`: Mapped to runtime path `/test-resources`
 
-    *Default configuration:*
-    ```yaml
+    ```yaml title="Default Configuration"
     resources:
       configuration:
         paths:
@@ -119,12 +131,11 @@ Note that all configured paths must be written in POSIX (i.e. using only forward
     ```
 
 === "Modules"
-    Any virtual paths can be mapped to any physical path.
+    Modules can map any virtual paths to any physical path within the project.
 
-    However, it is recommended that modules include their namespace in the virtual path and use the `/resources` prefix (e.g. `/resources/my/library/module-xy/`).
+    However, it is recommended that modules include their namespace in the virtual path and use the `/resources` prefix (e.g. `/resources/my/library/module-xy/`) to avoid name clashes with other projects.
 
-    *Example configuration:*
-    ```yaml
+    ```yaml title="Example Configuration"
     resources:
       configuration:
         paths:
@@ -135,17 +146,15 @@ Note that all configured paths must be written in POSIX (i.e. using only forward
 !!! example
     For an application project with the following directory structure, you need the path mapping configuration given below:
 
-    *Directory Structure*
-    ``` hl_lines="3 4 5"
+    ``` hl_lines="3 4 5" title="Directory Structure"
     my-app/
     \_ ui5.yaml
     \_ lib/
       \_ js/
         \_ app/
     ```
 
-    *Path Mapping Configuration*
-    ```yaml hl_lines="4"
+    ```yaml hl_lines="4" title="Path Mapping Configuration"
     resources:
       configuration:
         paths:

docs/updates/migrate-v3.md

@@ -16,18 +16,30 @@ Going forward, **only projects with Specification Versions 2.0 and higher are su
 In case a legacy specification version is detected, **an automatic migration is attempted.**
 This means your old projects might still work. Unless they have non-standard configuration in their ui5.yaml.
 
+## Changes for Projects
+
+!!! info
+    ✅ Projects defining **Specification Version 2.x** are expected to be **fully compatible with UI5 Tooling v3**
+
+For projects defining the latest **Specification Versions 3.0 and higher**, some changes apply:
+
+* **Breaking Change:** The `metadata.name` property is now restricted to contain only certain characters and no uppercase letters. See [Configuration: `name`](../pages/Configuration.md#name) for details
+
+Also see [Configuration: Specification Version 3.0](../pages/Configuration.md#specification-version-30-beta).
+
 ## Changes for Extensions
 
 !!! info
-    ✅ Custom Tasks and -Middleware defining **Specification Version 2.x and lower** are expected to be **fully compatible with UI5 Tooling v3**
+    ✅ Custom Tasks and -Middleware defining **Specification Version 2.x** are expected to be **fully compatible with UI5 Tooling v3**
 
 For extensions defining the latest **Specification Versions 3.0 and higher**, some changes and improvements apply:
 
 * **Breaking Change:** Custom Tasks need to request access to dependency resources
-  * By default, resources of dependencies can't be accessed. A custom task requiring such access needs to implement a callback function `determineRequiredDependencies`, in which it can also define the scope of dependency-access. Please refer to the [Custom Task: Required Dependencies documentation](../pages/extensibility/CustomTasks.md#required-dependencies)
+    * By default, resources of dependencies can't be accessed. A custom task requiring such access needs to implement a callback function with the export name `determineRequiredDependencies`. In this function it can define the scope of dependency-access. Please refer to the [Custom Task: Required Dependencies](../pages/extensibility/CustomTasks.md#required-dependencies) documentation for details
+* **Breaking Change:** The `metadata.name` property is now restricted to contain only certain characters and no uppercase letters. See [Configuration: `name`](../pages/Configuration.md#name) for details
 * **Features:** Enhanced TaskUtil and MiddlewareUtil API
-  * For example providing access to a [project's root directory](https://sap.github.io/ui5-tooling/v3/api/@ui5_project_build_helpers_TaskUtil.html#~ProjectInterface), or [dependencies](https://sap.github.io/ui5-tooling/v3/api/@ui5_project_build_helpers_TaskUtil.html#getDependencies)
-  * See also [Custom Tasks](../pages/extensibility/CustomTasks.md) and [Custom Server Middleware](../pages/extensibility/CustomServerMiddleware.md)
+    * For example providing access to a [project's root directory](https://sap.github.io/ui5-tooling/v3/api/@ui5_project_build_helpers_TaskUtil.html#~ProjectInterface), or [dependencies](https://sap.github.io/ui5-tooling/v3/api/@ui5_project_build_helpers_TaskUtil.html#getDependencies)
+    * See also [Custom Tasks](../pages/extensibility/CustomTasks.md) and [Custom Server Middleware](../pages/extensibility/CustomServerMiddleware.md)
 
 ## Changes to @ui5/project and @ui5/builder API