Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
164 lines (116 loc) · 4.17 KB

CONTRIBUTING.md

File metadata and controls

164 lines (116 loc) · 4.17 KB

Contributing to OXA

Prerequisites

Setup

# Install dependencies
pnpm install

Schema Development

The OXA schema is defined as individual YAML files in the schema/ directory. YAML was chosen for schema definitions because it is more human-readable and easier to edit than JSON.

The schema/schema.json file is autogenerated from the YAML sources and should not be edited directly. Any schema changes should be made to the .yaml files, then regenerated:

pnpm codegen json

Development Scripts

Formatting

# Format all files
pnpm format

# Check formatting without modifying files
pnpm format:check

Linting

# Check for lint issues
pnpm lint

# Auto-fix lint issues
pnpm lint:fix

Type Checking

# Run TypeScript type checking
pnpm typecheck

Code Generation

# Run all code generation (validate, ts, py, rs, docs, conformance)
pnpm codegen all

# Or run individual steps:
pnpm codegen validate     # Validate schema files
pnpm codegen ts           # Generate TypeScript types
pnpm codegen py           # Generate Python Pydantic models
pnpm codegen rs           # Generate Rust types
pnpm codegen conformance  # Generate conformance suite manifest
pnpm codegen docs         # Generate MyST documentation

Building

# Build all packages (uses Turborepo for caching and parallel execution)
pnpm build

# Clean all packages
pnpm clean

Note: This project uses Turborepo for build orchestration. Turborepo provides intelligent caching and parallel task execution across the monorepo, significantly speeding up builds and tests.

Releases

This project uses Changesets for version management and releases.

Adding a changeset

When you make changes that should be released, run:

pnpm changeset

This will prompt you to:

  1. Select which packages are affected
  2. Choose the bump type (patch, minor, major)
  3. Write a summary of the changes

Commit the generated changeset file with your PR.

Release process

  1. When PRs with changesets are merged to main, a "Version Packages" PR is automatically created/updated
  2. Merging the "Version Packages" PR triggers the release workflow
  3. Packages are published to:
    • npm: oxa-types, @oxa/core, oxa
    • PyPI: oxa-types
    • crates.io: oxa-types

Version synchronization

  • oxa-types (TypeScript), oxa-types (Python), and oxa-types (Rust) stay in sync
  • @oxa/core and oxa can version independently

Conformance Suite

The @oxa/conformance package provides test cases for validating OXA format conversion implementations. If you're building a tool that converts between OXA and other formats, you can use these test cases to validate your implementation.

To add new test cases to the conformance suite:

  1. Create a new JSON file in the appropriate directory:

    • packages/@oxa/conformance/cases/inline/ for inline node tests
    • packages/@oxa/conformance/cases/block/ for block node tests

  2. Follow the test case format:

{
  "$schema": "../../schemas/test-case.schema.json",
  "title": "Short descriptive title",
  "description": "What this test validates",
  "category": "inline",
  "formats": {
    "oxa": { ... },
    "myst": { ... },
    "pandoc": { ... },
    "stencila": { ... },
    "markdown": "...",
    "html": "...",
    "jats": "..."
  },
  "notes": {
    "markdown": "Optional format-specific notes"
  }
}

  1. Formats should be in canonical order: oxa, myst, pandoc, stencila, markdown, html, jats. The oxa format is required; others are optional.

  2. Regenerate the manifest:

pnpm codegen conformance
  1. Run tests to validate your test case:
pnpm test

Documentation

The documentation uses MyST and requires the automated codegen tool to run. To start the documentation use npm install -g mystmd and run myst start in the docs/ folder. The online documentation is hosted using Curvenote under https://oxa.dev