Layouting changes

rfcs/0006-local-dependency-resolution.md

@@ -48,12 +48,10 @@ A new kind of configuration file should be introduced, allowing to define "UI5 W
 
 For this, it should be possible to define locations at which UI5 Tooling will look for a dependency first, before falling back to the regular dependency resolution.
 
-**Examples:**
+#### Example: Overwrite Resolution of a Single Library
 
-------
-
-**ui5-workspace.yaml**
 ```yaml
+# ui5-workspace.yaml
 specVersion: workspace/1.0
 metadata:
     name: local-core
@@ -66,10 +64,10 @@ By configuring an additional resolution path, pointing to the directory of the s
 
 ![Workspace configuration for using local version of a single library](./resources/0006-workspace-setup/Workspace_Configuration_Single_Lib.svg)
 
-------
+#### Example: Overwrite Resolution of a Multiple Libraries
 
-**ui5-workspace.yaml**
 ```yaml
+# ui5-workspace.yaml
 specVersion: workspace/1.0
 metadata:
     name: local-openui5
@@ -78,22 +76,31 @@ dependencyManagement:
         - path: ../openui5
 ```
 
-For resolving all modules in OpenUI5, it should be enough to provide a path to the root directory. UI5 Tooling shall then use the [npm workspaces](https://docs.npmjs.com/cli/v8/using-npm/workspaces) configuration in the [package.json](https://github.com/SAP/openui5/blob/b74d3c2f153d7a23a2c9b914280b14b7289d7880/package.json#L128) to resolve all libraries located in the repository. Alternatively, a dedicated `ui5.workspaces` configuration in the package.json can be used.
+For resolving all modules in OpenUI5, it should be enough to provide a path to the root directory. UI5 Tooling shall then use the [npm workspaces](https://docs.npmjs.com/cli/v8/using-npm/workspaces) configuration in the [package.json](https://github.com/SAP/openui5/blob/b74d3c2f153d7a23a2c9b914280b14b7289d7880/package.json#L128) to resolve all libraries located in the repository. Alternatively, an equivalent `ui5.workspaces` configuration in the package.json can be used. If a `ui5.workspaces` configuration is found, the standard npm workspace configuration shall be ignored.
 
 ![Workspace configuration for using local version of all OpenUI5 libraries](./resources/0006-workspace-setup/Workspace_Configuration_All_OpenUI5.svg)
 
-------
+```jsonc
+// package.json in OpenUI5 repository root directory
+{
+  "name": "openui5",
+  // [...]
+  "workspaces": [
+    "src/!(testsuite-utils)"
+  ]
+}
+```
+
+#### Example: Standard Dependency Resolution
 
 For reference, this is how a standard dependency resolution, without a workspace configuration looks like. Dependencies of the openui5-sample-app are retrieved from the npm registry, stored in a central directory on the file system and used from there:
 
 ![Standard dependency resolution without workspace configuration](./resources/0006-workspace-setup/Standard_Dependency_Resolution.svg)
 
-------
+#### Example: Multiple Workspace Configurations
 
 Since every workspace configuration is identifiable by a name, multiple workspaces can be configured in the same file:
 
-**Example:**
-
 ```yaml
 specVersion: workspace/1.0
 metadata:
@@ -110,13 +117,13 @@ dependencyManagement:
         - path: ../openui5
 ```
 
-------
+#### Workspace Names
 
 Workspace names should be restricted in a reasonable matter (max length, only selected special characters). In addition, there shall be reserved names with special functionality:
 * `default`: This workspace should always be used, even if no `--workspace` parameter is provided to the CLI
-* `dev`: This workspace should always be used **unless**:
-    - there is a `default` workspace configured
-    - a production or CI environment is detected: **TODO: How?**
+* _~`dev`: This workspace should always be used **unless**:~_
+    - _~there is a `default` workspace configured~_
+    - _~a production or CI environment is detected: **TODO: How?**~_
 
 ### Key Design Decisions