5953685ffb
Includes: README explaining purpose / scope / temporary-location framing / format decision, CONTRIBUTING.md with proposed workflow + per-class semver versioning policy + validation commands, format/equipment-class.schema.json defining the shape of a class template (classId, version, displayName, applicability, signals, alarms, optional stateModel), format/tag-definition.schema.json defining the shape of a single canonical signal (name, dataType, category, unit, isArray, accessLevel, writeIdempotent, isHistorized, scaling), format/uns-subtree.schema.json defining the shape of a per-site UNS subtree (enterprise + site + areas + lines), classes/fanuc-cnc.json as the worked pilot class with 16 signals + 3 alarms + suggested state-derivation notes (per OtOpcUa corrections doc D1), uns/example-warsaw-west.json as a worked UNS subtree example, docs/overview.md (what / why / lifecycle / what's NOT in this repo), docs/format-decisions.md (8 numbered decisions covering JSON Schema choice per corrections D2, per-class semver, additive-only minor bumps, _default placeholder reservation, signal-name vs UNS-segment regex distinction, stateModel-as-informational, no per-equipment overrides at this layer, applicability.drivers as OtOpcUa driver enumeration), docs/consumer-integration.md (how OtOpcUa / Redpanda / dbt each integrate). $id URLs in the JSON schemas resolve at the actual current path so validators don't 404. Top-level README adds a row to the Component Detail Files table pointing to schemas/. Corrections doc B2 (schemas-repo dependencies) marked partially RESOLVED with the seed location and a list of what still needs the plan team or cross-team owner to decide (owner team naming, dedicated repo migration, format-decision ratification, FANUC CNC pilot confirmation, CI gate setup, Redpanda + dbt consumer integration plumbing). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
56 lines
2.9 KiB
Markdown
56 lines
2.9 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 dbt 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, dbt, 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`.
|