Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
134 lines (97 loc) · 4.61 KB

CONTRIBUTING.md

File metadata and controls

134 lines (97 loc) · 4.61 KB
Raw

Contributing to Open Coaching Format

Thank you for your interest in contributing to OCF. This document explains how to participate — whether you are a coach, developer, or sports scientist.

Types of Contributions

Bug Reports & Clarification Requests

If something in the schema or specification is unclear, incorrect, or inconsistent, please open a GitHub Issue with the label bug or clarification.

Include:

  • Which version of the schema you are using
  • The specific section or field in question
  • What you expected vs. what you found

Feature Requests

For new features (e.g. new entity types, additional rulesets, new line types), open an issue with the label enhancement and describe:

  • The use case (what coaching scenario requires this?)
  • Which sport(s) are affected
  • Whether it requires a schema version bump

RFC Process (Significant Changes)

Changes that affect the schema in a breaking or substantially additive way require a Request for Comments (RFC) before implementation.

What requires an RFC:

  • New top-level fields
  • New entity types or line types
  • Changes to the coordinate system
  • New ruleset definitions
  • Removing or renaming existing fields

What does NOT require an RFC:

  • Documentation improvements
  • New example files
  • Clarifications that don't change schema behavior
  • New named positions within an existing ruleset

RFC Workflow

  1. Open an issue describing the problem you want to solve
  2. Fork the repo and create a branch: rfc/your-feature-name
  3. Copy the RFC template: 
    cp rfcs/0000-template.md rfcs/XXXX-your-feature-name.md
    Use the next available RFC number.
  4. Fill in the RFC — motivation, detailed design, drawbacks, alternatives
  5. Open a Pull Request with the label rfc
  6. Discussion period: at least 14 days for community feedback
  7. Decision: maintainers mark the RFC as accepted, postponed, or rejected
  8. Implementation PR references the accepted RFC number

Pull Requests

For accepted RFCs and non-breaking changes:

  1. Fork and create a branch: feat/your-change or fix/your-fix
  2. Make your changes
  3. Validate example files against the schema: 
    npx ajv-cli validate -s schema/v1.json -d "examples/*.ocf.json"
  4. Open a Pull Request referencing the relevant issue or RFC

What Does Not Belong in the Public Repos

The OCF repositories are public and hold only artifacts meant to be published: the schema, the specification, code, examples, and RFCs. Competitive or market analyses, teardowns of other tools, and internal research notes should not be committed here — keep them in a private/internal location. Conclusions drawn from such research may of course inform a public RFC or issue, referenced by their result rather than by pasting the underlying material.

Code of Conduct

This project follows the Contributor Covenant v2.1. Be respectful, constructive, and inclusive.

Versioning Policy

OCF follows Semantic Versioning:

  • Patch (v1.0.x): Documentation fixes, clarifications, new examples
  • Minor (v1.x.0): Additive changes (new optional fields, new named positions, new rulesets)
  • Major (vX.0.0): Breaking changes to the schema

The schema file keeps a stable name across the whole v1 line: schema/v1.json is the canonical file (its $id is https://opencoachingformat.org/schema/v1.json) and it tracks the latest backwards-compatible 1.x release. The filename only changes for a breaking major (schema/v2.json). The current release version is recorded inside the schema ($comment) and in package.json.

Each release is also published to an immutable, version-pinned URL so implementations can pin exactly:

https://opencoachingformat.org/schema/v1.json          ← canonical, latest v1.x
https://opencoachingformat.org/<version>/ocf-action-v1.json  ← e.g. /v1.1.0/, immutable

Version-pinned copies are never removed — implementations can pin to a specific version.

Adding a New Ruleset

To add a new sport or league ruleset (e.g. EuroLeague, WNBA, 3x3, Wheelchair):

  1. Open an RFC describing the ruleset's court dimensions and geometry
  2. Define named positions in the spec (following the FIBA table format)
  3. Add the ruleset to the schema enum
  4. Add at least two example files using the new ruleset
  5. Document WCAG contrast for any new default colors

Questions?

Open an issue with the label question or start a discussion in GitHub Discussions.