Skip to content

Mature the pack SDK: stabilize, version, document, and decide on publishing #239

@larstalian

Description

@larstalian

What this is

Mature the extracted pack contract — openrange-pack-sdk and graphschema
(packages/, landed in #225 / #226) — from "in-tree workspace member" to a
stable, documented, independently-installable contract third-party pack
authors can depend on.

The whole architecture now hinges on this seam: packs depend only on the SDK
and must not import openrange. That boundary is enforced, but the contract
itself isn't yet treated as a published, versioned product.

What this covers

  • Stability + versioning. A semver policy for the SDK's public surface
    (Pack, TaskFamily, Builder, NPC/AgentNPC, Backing, RuntimeHandle,
    the graphschema IR). What's public vs. internal (_-prefixed) and what
    breaking-change means.
  • Publishing. Decide whether/when to publish to PyPI, or keep workspace-only.
    If published, CI release plumbing + changelog discipline (graphschema already
    has a CHANGELOG.md; the SDK doesn't yet).
  • Docs. The SDK README is ~70 lines; the contract surface needs reference
    docs. This is the substrate the pack-author guide (Write a pack-author guide #197) builds on.
  • Contract tests. A conformance test a candidate pack can run to prove it
    satisfies the contract without importing openrange.

Why now

A second pack just landed (trading, #194) and a third is proposed (SWE). Each
new pack is a fresh consumer of this contract; the cost of churning it grows with
every consumer. Stabilizing it now is cheaper than after N packs depend on it.

Where

Acceptance

A written stability/versioning policy, a decision on publishing, SDK reference
docs covering the public surface, and a contract-conformance test. Design doc /
ADR first.

Metadata

Metadata

Assignees

No one assigned

    Labels

    coreCore library / runtime / admissiondesign-neededNeeds a design pass before codedocumentationImprovements or additions to documentationroadmapTracked on the public roadmap

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions