98bf2d0da4
SnowBridge now owns machine-data ingest, in-process .NET transformation, and direct writes to curated tables in Snowflake. Collapses the previous ingest/transform split into a single service; no dbt, no external orchestrator, no Snowflake landing tier. Keeps the in-house .NET pattern consistent with ScadaBridge and OtOpcUa. The "Snowflake dbt Transform Layer" roadmap workstream merges into SnowBridge (7 → 6 workstreams); Year 2 canonical-state-based OEE moves with it. Canonical model still has three surfaces — the third is renamed from "dbt curated layer" to "SnowBridge curated layer in Snowflake"; mechanics unchanged.
56 lines
3.0 KiB
Markdown
56 lines
3.0 KiB
Markdown
# Contributing
|
|
|
|
> Initial seed by the OtOpcUa team. Future ownership TBD — the contribution process below is a starting suggestion the schemas-repo owner team should ratify or revise.
|
|
|
|
## Workflow (proposed)
|
|
|
|
1. **Open an issue first** for any new equipment class, UNS subtree, or format change. Describe the use case + the consumer(s) that need it.
|
|
2. **Branch + PR** — work on a feature branch, open a PR against `main`.
|
|
3. **CI gate** validates every JSON file against the schema in `format/`.
|
|
4. **Review** — at least one schemas-repo maintainer + one consumer-team representative (OtOpcUa, Redpanda, or SnowBridge depending on what changed).
|
|
5. **Merge + tag** — merge to `main` and create a semver tag. Consumers pin to tags.
|
|
|
|
## Adding a new equipment class
|
|
|
|
1. Create `classes/{class-id}.json` (lowercase hyphenated).
|
|
2. Reference the class schema: `"$schema": "../format/equipment-class.schema.json"`.
|
|
3. Fill in: `classId`, `version` (start at `0.1.0`), `displayName`, `vendor`, `applicability`, `signals`, optionally `alarms` and `stateModel`.
|
|
4. Validate locally — the CI gate will reject malformed JSON or schema violations.
|
|
5. Open the PR with a brief description of which equipment populations are covered.
|
|
|
|
## Adding a new UNS subtree
|
|
|
|
1. Create `uns/{site-name}.json`.
|
|
2. Reference the schema: `"$schema": "../format/uns-subtree.schema.json"`.
|
|
3. Fill in: `enterprise` (must match the org-wide value), `site`, `displayName`, `areas` with `lines`.
|
|
4. Coordinate with the OtOpcUa team — every cluster at the site must declare its `Enterprise` and `Site` matching this file.
|
|
|
|
## Format changes
|
|
|
|
Editing files in `format/` is a breaking change for downstream consumers. Process:
|
|
|
|
1. Open an issue with the proposed change + rationale.
|
|
2. Notify all consumer teams (OtOpcUa, Redpanda, SnowBridge, anyone else listed in `docs/consumer-integration.md`).
|
|
3. Get explicit signoff from each before merging.
|
|
4. Bump the major version of every affected class file simultaneously (consumers use this to detect breaking changes).
|
|
|
|
## Validation
|
|
|
|
```bash
|
|
# Per-file validation
|
|
ajv validate -s format/equipment-class.schema.json -d classes/fanuc-cnc.json
|
|
ajv validate -s format/uns-subtree.schema.json -d uns/example-warsaw-west.json
|
|
|
|
# Bulk validate everything
|
|
for f in classes/*.json; do ajv validate -s format/equipment-class.schema.json -d "$f"; done
|
|
for f in uns/*.json; do ajv validate -s format/uns-subtree.schema.json -d "$f"; done
|
|
```
|
|
|
|
## Versioning policy (proposed)
|
|
|
|
- **Major bump** (`0.x.y` → `1.x.y`) — breaking change: signal removed, signal renamed, dataType changed, isRequired changed false→true, alarm removed
|
|
- **Minor bump** (`x.0.y` → `x.1.y`) — additive non-breaking: new optional signal, new alarm, new state in stateModel, displayName/description updates
|
|
- **Patch bump** (`x.y.0` → `x.y.1`) — documentation/clarification only: description text updates, examples added, no semantic change
|
|
|
|
Consumers pin to a major.minor in production; staging environments can track `main`.
|