Contributing

DisclosureOS is an open standard — contributions of code, documentation, data, and design critique are all welcome. This page covers setup, the conventions the packages enforce, and what to expect from the process.

Where to contribute

• The foundation packages — records, observables, origins, scoring, schema, and the cli, under packages/ in the monorepo.
• The taxonomy and observables definitions — proposals to refine OCS nodes or observable criteria are standards work; open a discussion first so the change can be debated on the merits.
• The Disclosure Index — the flagship application built on the standard.
• Documentation — this site (apps/disclosureos) and package READMEs.

Development setup

Prerequisites: Node.js 20+ and pnpm 9+.

git clone https://github.com/disclosurefoundation/disclosureos
cd disclosureos && pnpm install

# work on a package
pnpm --filter @disclosureos/records test
pnpm --filter @disclosureos/records build

# run the whole gate locally
pnpm test && pnpm build

# the end-to-end smoke test
pnpm --filter @disclosureos/examples golden-path

Conventions the packages enforce

These aren't style preferences — CI checks them:

• Schema-first. Types are inferred from Zod schemas (z.infer), never written separately. If you add a field, you add it to the schema.
• The companion pattern. A new enum ships with its five companions — constants from Schema.options, a guard via makeGuard, labels, and formatter coverage where display matters.
• ESM-only, Node 20+. No CommonJS builds, no require patterns.
• Committed JSON Schema artifacts. Each package commits its generated schema under schema/. Drift tests regenerate and diff in CI — if your change alters the artifact, regenerate it and bump x-schema-version deliberately. A failing drift test is the system working.
• ValidationIssue everywhere. Validators return { path, message }[]; don't invent new error shapes.
• Slots, not forks. New evaluation surfaces attach through the records extension point and the runtime registry — never by editing ObservationSchema to know about satellites.

Changing the contract

Anything that alters the enriched observation shape — new fields, new slots, changed enums — is a contract change:

1. Open an issue or discussion before implementing; contract changes affect every consumer in every language.
2. Update the owning package's schema and regenerate its artifact.
3. Regenerate the composed artifact in @disclosureos/schema and update the drift tests.
4. Document the change in the package CHANGELOG (changesets drive versioning and publishing).

Additive optional fields are minor versions; anything that tightens or renames is major. When in doubt, ask in the issue.

Pull request process

1. For large or breaking changes, open an issue first so maintainers can align with you.
2. Branch from the default branch; keep PRs focused.
3. Add or update tests — guards, validators, factories, and formatters all have unit-test patterns to follow.
4. Run pnpm test && pnpm build plus the golden path before requesting review.
5. Describe why in the PR body, link related issues, and address review feedback.

Bugs and proposals

• Bugs — open an issue with reproduction steps, expected vs. actual behavior, and environment (OS, Node version).
• Standards proposals — for taxonomy nodes, observable definitions, or scoring methodology, describe the use case and the evidence basis. These changes are deliberately slower than code changes; the standard's value is its stability.

Code of conduct

The project follows a Code of Conduct. Report unacceptable behavior to os@disclosure.org.