Skip to content

Development

Jump to bottom
AstorisTheBrave edited this page Aug 30, 2026 · 2 revisions

Development

Identifold is specification-first and contains conforming packages for ten languages. The pnpm workspace coordinates the reference implementation, shared formatting, conformance runner, and TypeScript/Python examples; native workflows verify the remaining language packages and examples.

Baseline setup

git clone https://github.com/greyfoundry/identifold.git
cd identifold
pnpm install --frozen-lockfile
pnpm verify
pnpm test:coverage

Baseline development requires Node.js 22 or newer, pnpm 10.33.0 or a compatible pnpm 10 release, and Python 3.12 or newer. A language package or example also requires that language's native toolchain.

Repository map

Path Purpose
SPEC.md and spec/ Normative 1.0 contract and supporting rules
vectors/ Language-neutral compatibility corpus
conformance/ Adapter runner and manifests
packages/ Ten published implementations
examples/ Ten executable consumer examples
integrations/postgres/ Transactional REF storage boundary
.github/workflows/ Required CI, analysis, and publishing workflows

Change discipline

  • Change wire behavior in the specification and vectors before or with implementation changes.
  • Preserve deterministic values, normalization, and stable error classifications.
  • Add invalid and boundary vectors for compatibility changes.
  • Keep package APIs idiomatic without changing the shared wire contract.
  • Update the relevant executable example when a public API changes.
  • Keep public documentation and this wiki synchronized.

Verification

pnpm verify checks formatting, linting, types, tests, the TypeScript build, the TypeScript production example, conformance runner tests, and package exports. The language and Python workflows contain the pinned native commands for every other implementation and example.

Before considering a change complete, verify the local checks available to you and inspect the hosted result for every required job.

Pull requests

Keep changes focused and explain user-visible behavior, compatibility impact, security implications, and verification. Never include secrets, private identifiers, or personal data.

See CONTRIBUTING.md, Conformance and CI, and the roadmap.

Identifold

Clone this wiki locally