# 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`.