Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
59 lines (43 loc) · 1.66 KB

CONTRIBUTING.md

File metadata and controls

59 lines (43 loc) · 1.66 KB

Contributing to IOSM

Thank you for contributing to IOSM.

Contribution Principles

  • Preserve the normative meaning of the specification.
  • Keep repository examples aligned with the normative spec.
  • Update schemas, examples, and templates together when a structural change is introduced.
  • Use explicit change rationale in pull requests.
  • Avoid ambiguous wording around MUST, SHOULD, and MAY.

What to Update Together

If you change the normative spec, review whether the following also require updates:

  • README.md
  • IOSM_SPEC_v1.0.md
  • artifacts/examples/*
  • artifacts/templates/*
  • schemas/*.schema.json
  • scripts/validate_repository.py
  • .github/workflows/validate-spec-repo.yml
  • requirements-dev.txt
  • CHANGELOG.md

Local Validation

Before opening a pull request, run:

python3 -m pip install -r requirements-dev.txt
make validate

Pull Request Checklist

  • The change is consistent with the current IOSM version.
  • The repository examples still match the spec.
  • Any affected schema has been updated.
  • Local validation passes (make validate).
  • New normative requirements are explicitly stated.
  • Versioning impact is described in the pull request body.

Versioning Guidance

  • Use patch-level repository changes for clarifications and non-breaking repository improvements.
  • Use a new versioned spec file for incompatible normative changes.
  • Do not silently rewrite old spec versions.

Reporting Gaps

Open an issue or pull request if you find:

  • inconsistent normative language;
  • missing artifact coverage;
  • schema/spec mismatches;
  • incomplete examples;
  • ambiguity in gate semantics, evidence rules, or stabilization logic.