Merge branch 'main' into add_sonarcloud

.github/workflows/add-pr-to-board.yml

@@ -0,0 +1,103 @@
+# SPDX-FileCopyrightText: 2023 Alliander N.V.
+#
+# SPDX-License-Identifier: Apache-2.0
+
+name: Add pull requests to the overview board
+
+on:
+  workflow_run:
+    workflows: [Prepare PR data]
+    types: [completed]
+
+env:
+  todo: Pending
+  changes_requested: Changes Requested
+  approved: Approved
+
+jobs:
+  read-data-and-automate:
+    runs-on: ubuntu-latest
+    if: github.event.workflow_run.conclusion == 'success'
+    outputs:
+      pr_node_id: ${{ steps.pr_node_id.outputs.content }}
+      event_action: ${{ steps.event_action.outputs.content }}
+      review_pr_node_id: ${{ steps.review_pr_node_id.outputs.content }}
+      review_state: ${{ steps.review_state.outputs.content }}
+    steps:
+      # Data retrieval steps in case of a PR event
+      - name: Download PR data artifact
+        if: github.event.workflow_run.event == 'pull_request' || github.event.workflow_run.event == 'pull_request_target'
+        uses: dawidd6/action-download-artifact@v2
+        with:
+          workflow: Prepare PR data
+          run_id: ${{ github.event.workflow_run.id }}
+          name: PR_DATA
+      - name: Read PR event's PR_NODE_ID.txt
+        if: github.event.workflow_run.event == 'pull_request' || github.event.workflow_run.event == 'pull_request_target'
+        id: pr_node_id
+        uses: juliangruber/read-file-action@v1
+        with:
+          path: ./PR_NODE_ID.txt
+          trim: true
+      - name: Read PR event's EVENT_ACTION.txt
+        if: github.event.workflow_run.event == 'pull_request' || github.event.workflow_run.event == 'pull_request_target'
+        id: event_action
+        uses: juliangruber/read-file-action@v1
+        with:
+          path: ./EVENT_ACTION.txt
+          trim: true
+      # Data retrieval steps in case of a PR review event
+      - name: Download PR review data artifact
+        if: github.event.workflow_run.event == 'pull_request_review'
+        uses: dawidd6/action-download-artifact@v2
+        with:
+          workflow: Prepare PR data
+          run_id: ${{ github.event.workflow_run.id }}
+          name: REVIEW_DATA
+      - name: Read PR review event's PR_NODE_ID.txt
+        if: github.event.workflow_run.event == 'pull_request_review'
+        id: review_pr_node_id
+        uses: juliangruber/read-file-action@v1
+        with:
+          path: ./PR_NODE_ID.txt
+          trim: true
+      - name: Read PR review event's REVIEW_STATE.txt
+        if: github.event.workflow_run.event == 'pull_request_review'
+        id: review_state
+        uses: juliangruber/read-file-action@v1
+        with:
+          path: ./REVIEW_STATE.txt
+          trim: true
+      # Project automation steps
+      - name: Move PR to ${{ env.todo }}
+        if: ((github.event.workflow_run.event == 'pull_request' ||
+          github.event.workflow_run.event == 'pull_request_target') &&
+          (steps.event_action.outputs.content == 'opened' ||
+          steps.event_action.outputs.content == 'reopened')) ||
+          (github.event.workflow_run.event == 'pull_request_review' &&
+          steps.review_state.outputs.content == 'dismissed')
+        uses: leonsteinhaeuser/[email protected]
+        with:
+          project_id: 7
+          gh_token: ${{ secrets.ORG_GITHUB_ACTION_SECRET }}
+          organization: openscd
+          resource_node_id: ${{ github.event.workflow_run.event == 'pull_request_review' && steps.review_pr_node_id.outputs.content || steps.pr_node_id.outputs.content }}
+          status_value: ${{ env.todo }}
+      - name: Move PR to ${{env.approved}}
+        if: github.event.workflow_run.event == 'pull_request_review' && steps.review_state.outputs.content == 'approved'
+        uses: leonsteinhaeuser/[email protected]
+        with:
+          project_id: 7
+          gh_token: ${{ secrets.ORG_GITHUB_ACTION_SECRET }}
+          organization: openscd
+          resource_node_id: ${{ steps.review_pr_node_id.outputs.content }}
+          status_value: ${{ env.approved }}
+      - name: Move PR to ${{env.changes_requested}}
+        if: github.event.workflow_run.event == 'pull_request_review' && steps.review_state.outputs.content == 'changes_requested'
+        uses: leonsteinhaeuser/[email protected]
+        with:
+          project_id: 7
+          gh_token: ${{ secrets.ORG_GITHUB_ACTION_SECRET }}
+          organization: openscd
+          resource_node_id: ${{ steps.review_pr_node_id.outputs.content }}
+          status_value: ${{ env.changes_requested }}

.github/workflows/build-and-deploy.yml

@@ -7,6 +7,10 @@ on:
 jobs:
   build-and-deploy:
     runs-on: ubuntu-latest
+    defaults:
+      run:
+        shell: bash
+        working-directory: packages/open-scd
     steps:
       - name: Checkout
         uses: actions/[email protected]
@@ -18,13 +22,13 @@ jobs:
 
       - name: Install and Build
         run: |
-          npm ci
+          npm clean-install
           npm run-script build
-          
+
       - name: Deploy
         uses: JamesIves/[email protected]
         with:
           branch: master
-          folder: build
+          folder: packages/open-scd/build
           repository-name: openscd/openscd.github.io
-          ssh-key: ${{ secrets.DEPLOY_KEY }}
+          ssh-key: ${{ secrets.DEPLOY_KEY }}

.github/workflows/save-pr-data-to-file.yml

@@ -0,0 +1,37 @@
+# SPDX-FileCopyrightText: 2023 Alliander N.V.
+#
+# SPDX-License-Identifier: Apache-2.0
+
+name: Prepare PR data
+# Necessary step to allow adding external PRs to the project board
+
+on: [pull_request, pull_request_target, pull_request_review]
+
+jobs:
+  save-pr-data:
+    name: Save PR data to file
+    runs-on: ubuntu-latest
+    if: ${{ github.event.pull_request.user.login != 'github-actions[bot]' }}
+    steps:
+      - name: Save PR node_id and event_action to files
+        if: github.event_name == 'pull_request' || github.event_name == 'pull_request_target'
+        run: echo ${{ github.event.pull_request.node_id }} > PR_NODE_ID.txt && echo ${{ github.event.action }} > EVENT_ACTION.txt
+      - name: Archive PR node_id and event_action
+        if: github.event_name == 'pull_request' || github.event_name == 'pull_request_target'
+        uses: actions/upload-artifact@v3
+        with:
+          name: PR_DATA
+          path: |
+            PR_NODE_ID.txt
+            EVENT_ACTION.txt
+      - name: Save PR node_id and review_state to files
+        if: github.event_name == 'pull_request_review'
+        run: echo ${{ github.event.pull_request.node_id }} > PR_NODE_ID.txt && echo ${{ github.event.review.state }} > REVIEW_STATE.txt
+      - name: Archive PR and review_state
+        if: github.event_name == 'pull_request_review'
+        uses: actions/upload-artifact@v3
+        with:
+          name: REVIEW_DATA
+          path: |
+            PR_NODE_ID.txt
+            REVIEW_STATE.txt

.github/workflows/stale-issues.yml

@@ -0,0 +1,44 @@
+# This workflow labels stale issues.
+#
+# For more information, see:
+# https://github.com/actions/stale
+name: Mark stale issues
+
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: '0 19 * * *'
+
+jobs:
+  stale:
+    runs-on: ubuntu-latest
+    permissions:
+      issues: write
+
+    steps:
+    - uses: actions/stale@v5
+      with:
+        repo-token: ${{ secrets.GITHUB_TOKEN }}
+
+        days-before-stale: 60
+        days-before-close: -1
+        days-before-pr-stale: -1
+        days-before-pr-close: -1
+
+        stale-issue-label: 'stale'
+        stale-issue-message: |
+          Hello there,
+
+          Thank you for opening this issue! We appreciate your interest in our project.
+          However, it seems that this issue hasn't had any activity for a while. To ensure that our issue tracker remains organized and efficient, we occasionally review and address stale issues.
+
+          If you believe this issue is still relevant and requires attention, please provide any additional context, updates, or details that might help us understand the problem better.
+          Feel free to continue the conversation here.
+
+          If the issue is no longer relevant, you can simply close it. If you're uncertain, you can always reopen it later.
+
+          Remember, our project thrives on community contributions, and your input matters. We're here to collaborate and improve.
+          Thank you for being part of this journey!
+
+
+

.github/workflows/test-and-build.yml

@@ -15,5 +15,6 @@ jobs:
 
       - name: Install and Build
         run: |
-          npm ci
-          npm run-script build
+          cd packages/open-scd
+          npm clean-install
+          npm run-script build

.github/workflows/test.yml

@@ -1,5 +1,5 @@
 name: Test
-on: 
+on:
   push:
     branches-ignore:
       - main
@@ -18,5 +18,6 @@ jobs:
 
       - name: Install and Test
         run: |
-          npm ci
-          npm run-script test
+          cd packages/open-scd
+          npm clean-install
+          npm run-script test

.gitignore

@@ -6,17 +6,5 @@
 .DS_Store
 
 ## npm
-/node_modules/
+node_modules/
 /npm-debug.log
-
-## testing
-/coverage/
-/**/dist/*.snap.dev.js
-
-## docs
-/doc/
-
-# build
-/_site/
-/build/
-/out-tsc/

README.md

@@ -19,52 +19,22 @@ In order to install your own instance of OpenSCD on your own webserver (e.g. on
 
 If you don't have your own webserver but still want your own version of OpenSCD hosted locally (e.g. on a system without an internet connection), you can [use a browser plugin that acts as a local webserver](https://github.com/openscd/open-scd/wiki/Install-OpenSCD#offline) (only for you) instead.
 
-## Contributing
-
-The easiest way to get in touch is to join the `#open-scd` channel kindly hosted on [the LF Energy Slack server](https://lfenergy.slack.com/archives/C03LH7EUP34). 
-If you say "hi" there we will be more than happy to help you find your way around this project.
-
-### Building
-
-If you want to build OpenSCD yourself in order to make some changes to your local installation or to contribute to the project, you may first want to install [Node.js](https://nodejs.org/) in order to be able to use our local development setup. It is recommended to use Node.js 18.x. it is is the version used to build and test on GitHub Actions.
-
-Once Node.js is installed on your system, you may get started by entering the following lines in your command prompt:
-
-```
-git clone https://github.com/openscd/open-scd.git
-cd open-scd
-npm install
-npm start
-```
 
-This will start a local development server and open a browser window which will automatically be reloaded as soon as you save any changes to your local source code files.
+## Development
 
-### TypeDoc
+This repository is a [↗ monorepo](https://en.wikipedia.org/wiki/Monorepo), made up of several packages.
+To find out more about the development of each packages, such as the base distribution or the plugins, please refer to their respective READMEs:
+- [open-scd](packages/open-scd/README.md): provides the base distribution available on [openscd.github.io](https://openscd.github.io)
 
-This project uses [TypeDoc](https://typedoc.org/) to transform documentation comments in the source code into a rendered HTML document that can be queried and navigated through. If you want to consult the generated documentation for the TypeScript components, mixins, modules and other relevant artifacts of this project, you can [do it here](https://openscd.github.io/doc/).
-
-### Linting & Formatting
-
-If you use VSCode to develop, we recommend you install and use the [ESLint](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint) and [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) extensions in order to automatically lint and format your code as you edit it. There are similar plugins available for using [ESLint](https://eslint.org/) and [Prettier](https://prettier.io/) from within other IDEs and text editors.
-
-### Scripts
-
-We provide the following `npm` scripts for your convenience:
-
-- `npm start` runs `OpenSCD` for development, reloading on file changes
-- `npm test` runs the test suite with Karma
-- `npm run lint` runs the linter (fixes problems in your code)
-- `npm run format` runs the formatter (formats your code in a unified way)
-- `npm run doc` builds HTML documentation into the `doc` directory
-- `npm run build` builds a deployable version of the project into the `dist` directory
+## Contributing
 
-## License
+The easiest way to get in touch is to join the `#open-scd` channel kindly hosted on [the LF Energy Slack server](https://lfenergy.slack.com/archives/C03LH7EUP34). 
+If you say "hi" there we will be more than happy to help you find your way around this project.
 
-The [IEC 61850](https://webstore.iec.ch/publication/63319) XSD and NSD code components used are
-distributed under their [end user license agreement](CC-EULA.pdf).
+## Documentation
 
-This project is licensed under the [Apache License 2.0](LICENSE.md).
+How the documentation is organized.
 
-© 2020-2022 OMICRON electronics GmbH, TransnetBW GmbH, Alliander N.V., and others
+A high-level overview of how it’s organized will help you know where to look for certain things:
 
-[![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Fopenscd%2Fopen-scd.svg?type=large)](https://app.fossa.com/projects/git%2Bgithub.com%2Fopenscd%2Fopen-scd?ref=badge_large)
+- [⚖️ Decisions](docs/decisions/README.md) documents the decisions we made and why we made them.

docs/decisions/0001-record-architecture-decisions.md

@@ -0,0 +1,28 @@
+# 1. Record architecture decisions
+
+Date: 2023-07
+
+## Status
+
+Accepted
+
+## Context
+
+We need to record the architectural decisions made on this project.
+
+## Decision
+
+We will follow the decisions recorded in the central organizational 
+repository ([.github](https://github.com/openscd/.github)), 
+and record new repo-specific decisions in this repository.
+
+
+We write ADRs in the `docs/decisions` folder instead of a standard `doc/adr`:
+- `docs` instead of `doc` because `doc` is used for the generated documentation.
+- `decisions` instead of `adrs` because it is more explicit and a followed practice:
+  [↗ Markdown Any Decision Records - Applying MADR to your project ](https://adr.github.io/madr/#applying-madr-to-your-project)
+
+## Consequences
+
+- It will be harder to track which decisions have to be taken into consideration
+- Local decisions will be easier to find

docs/decisions/0002-use-monorepo.md

@@ -0,0 +1,33 @@
+# 2. Use Monorepo
+
+Date: 2023-08
+
+## Status
+
+Accepted
+
+## Context
+
+We want:
+  - better access management to core functionalities, plugins and ui components
+  - easier maintainability and refactorability of critical parts
+  - more shareable code
+
+
+## Decision
+
+We will use a monorepo to manage the codebase for the time being. 
+
+To control access to the codebase we will use CODEOWNERS files.
+
+
+## Consequences
+
+- it makes the the dependency discovery and management easier between packages
+- we can add packages that can be deployed and published independently and still used directly inside the monorepo
+- it will allow us to experiment and beta test packages before publishing them
+- CI pipeline runs will be faster because changes are more separated
+- it will make it harder to bundle and distribute parts of the base distribution
+- it moves the complexity of package management into a concentrated place
+
+

docs/decisions/README.md

@@ -0,0 +1,4 @@
+# Decisions
+
+- [ADR-0001: Record architecture decisions](0001-record-architecture-decisions.md) <kbd>✅ active</kbd>
+- [ADR-0002: Use Monorepo](0002-use-monorepo.md) <kbd>✅ active</kbd>