infra: switch to monorepo

Author: Tamás Russ

.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
           repository-name: openscd/openscd.github.io
-          ssh-key: ${{ secrets.DEPLOY_KEY }}
+          ssh-key: ${{ secrets.DEPLOY_KEY }}

.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/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>