Merge branch 'main' into release-please--branches--main--components--…

…openscd-monorepo

.github/workflows/attach-release-assets.yml

@@ -0,0 +1,38 @@
+on:
+  release:
+    types: [published]  # This triggers when a new release is published
+
+permissions:
+  contents: write
+
+name: attach-release-assets
+
+jobs:
+  attach-assets:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/[email protected]
+      - name: Use Node.js 18.x
+        uses: actions/setup-node@v1
+        with:
+          node-version: "18.x"
+      - name: Install and Build OpenSCD
+        run: | 
+          npm i @nx/nx-linux-x64-gnu
+          npm clean-install
+          npm run-script build
+          npm run-script doc
+      - name: Copy Core Docs to OpenSCD
+        run: cp -R packages/core/doc packages/distribution/build/core-doc
+
+      - name: Copy Plugin Docs to OpenSCD
+        run: cp -R packages/plugins/doc packages/distribution/build/plugin-doc
+
+      - name: Compress files
+        run: tar -czf open-scd.tar.gz -C packages/distribution/build
+
+      - name: Upload release files
+        run: gh release upload ${{ steps.release.outputs.tag_name }} open-scd.tar.gz
+        env: 
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

docs/decisions/0003-extract-plugins.md

@@ -0,0 +1,36 @@
+# ADR-0003 - Externalize OpenSCD core plugins
+
+Date: 2024-11-19
+
+## Status
+
+Approved
+
+## Context
+
+For a better expandability we would like to extract all plugins in a new plugins repository.
+
+## Decision
+
+Following the architectural decision in [OpenSCD Theming](./../0001-ADR-Theming.md) we will extract all OpenSCD Core plugins to an external repository.
+Doing so OpenSCD Core will be streamlined and a clean interface and structure for plugins will be provided for custom extensions.
+Before extracting this plugins a shared UI-Components module will be extracted. This UI-Components provide reusable UI-Components based on [NX](https://nx.dev/) for faster development for OpenSCD Core and custom plugins. This new repository will be created as mono repository to facility the plugins development and simplify the release and deployment process.
+
+Plugins will be moved to repository [OpenSCD official Plugins](https://github.com/openscd/oscd-official-plugins) and the release strategy is defined [here](./0004-openscd-release-and-deploy-strategy.md).
+As final task the current documentation will be added with a new section `How to add new and custom OpenSCD plugins` to support developers to follow the concept.
+
+## Consequences
+
+- Clean Code in OpenSCD Core
+- Clear architectural structure of plugins
+
+- Building OpenSCD is more then building a simple repository
+- Clear path must be defined how to extend OpenSCD with custom plugins (full software cycle till deployment)
+- Release process for OpenSCD Core and OpenSCD official plugins
+
+## Agreed procedure
+
+- move the plugins without any components abstraction to the external plugins repository
+  - copy all required dependencies regardless of code duplication
+- integrate the plugins as submodules within OpenSCD core in the pipeline
+- later on we can extract step by step for each plugin UI-Components

docs/decisions/0004-openscd-release-and-deployment-strategy.md

@@ -0,0 +1,32 @@
+# ADR-0004 - Technical solution for releasing and deployments
+
+Date: 2024-11-19
+
+## Status
+
+Approved
+
+## Context
+
+Based on the [decision](./0003-extract-plugins.md) to externalize plugins in proper plugins repository a new release and deployment strategy needs to be defined.
+This plugins repository is solved as mono repository.
+
+## Decision
+
+### Release process 
+
+Since OpenSCD is based on [NX](https://nx.dev/) the release strategy needs to rely on NX as well and must allow single releases of sub modules within this mono repository.
+Such feature is provided by [NX release](https://nx.dev/recipes/nx-release) specially when using the [NX independently release feature](https://nx.dev/recipes/nx-release/release-projects-independently).
+
+A possible release command would look like:
+```
+  nx release --projects=plugin-1,plugin-3
+```
+
+## Consequences
+
+- Process needs to be documented so that all developers can easily follow it
+- The building of complete OpenSCD Editor, OpenSCD Core + OpenSCD plugins, depends now on two repositories
+- Custom OpenSCD eg. CoMPAS OpenSCD will be cleaner and more code can be reused
+- Similar Look & Feel of plugins if shared UI-Components are used
+- Faster plugin development and integration into OpenSCD Core

packages/openscd/package.json

@@ -172,4 +172,4 @@
     ],
     "commitUrlFormat": "https://github.com/openscd/open-scd/commits/{{hash}}"
   }
-}
+}

packages/openscd/src/open-scd.ts

@@ -254,7 +254,7 @@ export class OpenSCD extends LitElement {
 
   private resetPlugins(): void {
     this.storePlugins(
-      (builtinPlugins as Plugin[]).concat(this.parsedPlugins).map(plugin => {
+      (this.getBuiltInPlugins() as Plugin[]).concat(this.parsedPlugins).map(plugin => {
         return {
           ...plugin,
           installed: plugin.default ?? false,
@@ -316,7 +316,7 @@ export class OpenSCD extends LitElement {
       const isBuiltIn = !plugin?.official
       if (!isBuiltIn){ return plugin };
 
-      const builtInPlugin = [...builtinPlugins, ...this.parsedPlugins]
+      const builtInPlugin = [...this.getBuiltInPlugins(), ...this.parsedPlugins]
         .find(p => p.src === plugin.src);
 
         return <Plugin>{
@@ -367,14 +367,14 @@ export class OpenSCD extends LitElement {
     const localPluginConfigs = this.getPluginConfigsFromLocalStorage()
 
     const overwritesOfBultInPlugins = localPluginConfigs.filter((p) => {
-      return builtinPlugins.some(b => b.src === p.src)
+      return this.getBuiltInPlugins().some(b => b.src === p.src)
     })
 
     const userInstalledPlugins = localPluginConfigs.filter((p) => {
-      return !builtinPlugins.some(b => b.src === p.src)
+      return !this.getBuiltInPlugins().some(b => b.src === p.src)
     })
 
-    const mergedBuiltInPlugins = builtinPlugins.map((builtInPlugin) => {
+    const mergedBuiltInPlugins = this.getBuiltInPlugins().map((builtInPlugin) => {
       const noopOverwrite = {}
       const overwrite = overwritesOfBultInPlugins
         .find(p => p.src === builtInPlugin.src)
@@ -383,7 +383,6 @@ export class OpenSCD extends LitElement {
       return {
         ...builtInPlugin,
         ...overwrite,
-        installed: true, // TODO: is this correct? should we decide it based on something?
       }
     })
 
@@ -404,6 +403,10 @@ export class OpenSCD extends LitElement {
     this.storePlugins(newPlugins);
   }
 
+  protected getBuiltInPlugins(): CorePlugin[] {
+    return builtinPlugins as CorePlugin[]
+  }
+
   private addContent(plugin: Omit<Plugin, 'content'>): Plugin {
     const tag = this.pluginTag(plugin.src);
 

packages/openscd/src/plugins.ts

@@ -1,4 +1,4 @@
-function generatePluginPath(plugin: string): string {
+export function generatePluginPath(plugin: string): string {
   return location.origin+location.pathname+plugin;
 }