Distribution strategy for customer-branded CoMPAS deployments

[david-monichi]

Purpose

As a CoMPAS integrator I want to be able to create customer-branded deployment
container. For this a customer needs a concrete way to produce that container. This
document proposes how customer repositories should reference the CoMPAS
codebase and how upstream updates should flow.

Current State

Today, com-pas/compas-open-scd is the CoMPAS application. It is not
consumed by other repositories.

• Reusable OpenSCD/CoMPAS pieces come from published npm packages such as
  @compas-oscd/core, @compas-oscd/open-scd, @compas-oscd/plugins, and
  @openscd/oscd-editor.
• External plugins are integrated as git submodules under
  packages/external-plugins/ and copied into the build.
• The application shell, header, plugin registry, translations, and services
  all live in src/. There is no separate published CoMPAS core package that a
  customer repository could depend on.

That means the abstraction alone is not enough. CoMPAS also needs to expose the
customer-facing pieces (shell entry point, header contract, default header,
default theme) in a form customers can consume.

Proposed Strategy: Publish A CoMPAS Core Package

Split this repository into two concerns:

• A published package, for example @compas/open-scd-core, containing the
  application shell, header contract, default header, default theme, plugin
  bootstrap, translations, and services.
• A reference deployment container. This repository can continue to be the
  default CoMPAS deployment consuming that package. Every customer produces
  their own deployment container the same way.

com-pas/compas-open-scd          publishes @compas/open-scd-core
                                 + default deployment container

customer-<name>/<name>-open-scd  customer deployment container
                                 depends on @compas/open-scd-core

What A Customer Repository Contains

A customer repository is small and owns only what actually differs.

customer-acme-open-scd/
  package.json
  src/
    acme-header.ts        # header module implementing the CoMPAS contract
    acme-theme.css        # overrides for documented --compas-* tokens
    main.ts               # boots CoMPAS with the customer header + theme
  public/
    acme-logo.svg

package.json in the customer repository:

{
  "name": "customer-acme-open-scd",
  "dependencies": {
    "@compas/open-scd-core": "^1.0.0"
  }
}

src/main.ts:

import '@compas/open-scd-core/default-theme.css';
import './acme-theme.css';

import { startCompasApplication } from '@compas/open-scd-core';
import { acmeHeader } from './acme-header.js';

startCompasApplication({ header: acmeHeader });

src/acme-theme.css overrides only documented tokens:

:root {
  --compas-color-primary: #005b96;
  --compas-color-secondary: #007c91;
  --compas-color-surface: #ffffff;
  --compas-color-text: #17212b;
  --compas-color-error: #b42318;
}

src/acme-header.ts implements the versioned CoMPAS header contract from the
parent proposal. It renders only CoMPAS-provided actions.

How Upgrades Flow

• CoMPAS releases @compas/open-scd-core with SemVer.
• A customer upgrades by bumping the dependency version, running the build,
  and testing the container.
• Non-breaking updates require no customer code changes.
• Breaking changes appear as a new major version. The customer updates the
  header module or CSS overrides only where the public contract changed.
• Plugin availability and behavior are inherited from the core package. The
  customer does not maintain a plugin catalog.

[Sander3003]

We discussed briefly today, we (Alliander) are happy with the direction. @clepski has some concerns whether we need to fix some foundational issues first, see below (@clepski will reply below).

[clepski]

We should probably start one level lower at the open-scd package, currently there is still some copy-pasted code (plugin handling, open-scd component, and some other stuff) in compas-open-scd. Once that is in a good state and you can create your own distribution with maybe 150 lines of code or so, we can move on to compas-open-scd.

To be fair, we haven't spend much thought or time on theming or branding, so there is definately room for improvement. When creating your own distribution you can completely overwrite the oscd-layout component and put in anything you want, but there might still be some code you would have to take over from the original component.

[Sander3003]

On the Theming topic, we could cosider the standardise the approach in an OpenSCD guideline for all plug-ins.