OpenResidency Docs

Contributing

The contribution workflow — from signed-commit setup through issue, core-behind-boundary implementation, a matching test assertion, and a green, signed PR.

The repeatable loop for landing a change. Two habits carry through everything: put the logic in core behind the boundary, and every core change gets a scripts/*.ts assertion.

0. On-ramp (once)

  • Signed commits are required — main rejects unsigned pushes. Set up SSH signing (gpg.format ssh, commit.gpgsign true), register the key on GitHub as a Signing Key (not Authentication), and ensure your commit email is a verified email on your account. Verify with git log --format='%h %G? %s' -3 → you want G.
  • npm install && npm test → green (hermetic: no DB, no network).

The loop

  1. Pick an issue. Edge / no-dependency fixes first. Anything touching the privacy or security model needs discussion in the issue before coding (governance gate). Security disclosures go via SECURITY.md, not a public issue.
  2. Understand the code path. Read the file and the scripts/*.ts smoke that covers it.
  3. Branch off fresh main (protected — PR only): fix/<purpose>, signed commits.
  4. Implement. Put decision-logic in src/core behind a port; keep the controller thin; preserve the boundary (zero framework imports in core).
  5. Test. Add or update a scripts/*.ts assertion — mandatory for core changes, or the PR is sent back.
  6. Verify. npm test green ⇒ green in CI (the suites are hermetic).
  7. Self-review. Correctness, performance, security, conventions.
  8. Fix findings, re-test.
  9. Docs. Update docs/INTEROP.md for anything a wallet/verifier sees; docs/openapi.yaml for HTTP-surface changes.
  10. Ship. Signed commit (Closes #<n>, one concern, say why, note security implications) → push → open the PR.

The two non-negotiables

Logic in core behind the boundary, and a matching scripts/*.ts assertion for every core change. Internalise those plus the trust-flow spine and you have both the system and the process.

What CI gates

Prisma client generation → typecheck → the core / OpenID4VCI / OpenID4VP / SSO / W3C-conformance suites → Docker image build. All hermetic, so a green npm test locally is a green CI run.

Source: CONTRIBUTING.md, .github/workflows/ci.yml.

What not to break

The security and privacy invariants that are the whole point of OpenResidency — do not relax them to make something work; narrow the config instead.

Glossary

The terms you'll meet across OpenResidency — from DID and VC to subjectRef, pairwise sub, and RAL.

On this page

0. On-ramp (once)The loopWhat CI gates