Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
105 lines (81 loc) · 4.25 KB

CONTRIBUTING.md

File metadata and controls

105 lines (81 loc) · 4.25 KB

Contributing to Patra

Patra is the universal schema for government correspondence. Every state has agencies. Every agency has notices. We can't cover all of them alone, and we don't need to — the whole point of an open standard is that the ecosystem extends it together.

What to contribute

New state agencies

The fastest way to help. Open a PR adding one or more agency descriptors to src/registry/agencies.ts. Use the existing agency({ ... }) helper, the same naming conventions, and put the entries in the right jurisdictional section. A good entry includes the agency's canonical website URL in the website field.

New notice types

If your state or agency issues a notice that isn't already covered, add it. A complete notice-type PR touches four files:

  1. src/types/payload.ts — add the payload interface with real fields from an actual notice. Don't invent fields. If a notice has five boxes, the interface has five fields.
  2. src/types/payload.ts again — add the type to the PatraPayload union and to PAYLOAD_TYPES.
  3. src/registry/notice-types.ts — add a NoticeTypeEntry with the UGCS code, domain, typical agencies, and known agency form numbers.
  4. tests/fixtures/ — add at least one fixture JSON file with realistic data. Anonymize everything: use EIN 31-1234567, SHA-256-looking hashes of placeholder SSNs, fake business names.

Statute references

The deadline calculator needs a statute rule per jurisdiction+UGCS-code pair to auto-compute deadlines. If you know the statutory response window for a notice type in your jurisdiction, open a PR adding it to src/registry/statutes.ts.

Cite the actual statute or regulation. Vague entries get rejected — "California usually gives 30 days" isn't useful. Cal. Rev. & Tax Code 19041 — 60 calendar days from issue date is.

State holiday calendars

By default Patra uses federal holidays + Ohio observances. Adding your state's observed days means the deadline calculator computes the right business-day math for your jurisdiction. Use registerHolidays(jurisdiction, year, [...]) or open a PR adding a dedicated helper alongside ohioHolidays in src/utils/holidays.ts.

Bug fixes and tests

Patra's test suite (npm test) runs every fixture through the validator and exercises the calculator and registries. If you find a bug, the PR should include a failing test that your fix makes pass.

What NOT to contribute

  • Adapters. Adapters belong in separate packages (@your-org/patra-agency-x). The core @kreto/patra package is deliberately minimal — types, registries, validator, calculator. Nothing that parses.
  • Sensitive fixture data. Every fixture must be fully synthetic. No real SSNs, EINs, business names, or case numbers. The validator rejects raw SSNs in the ssn_hash field, but it can't tell that a business name is real. Don't put one in.
  • Breaking changes without an ADR. If you want to change the envelope, rename a field, or remove a payload type, open an issue first with an Architecture Decision Record describing the change and its migration path. Not all changes are accepted.

PR checklist

Before submitting:

  • npm test passes
  • npm run typecheck passes
  • Any new notice types have a fixture that validates
  • Any new agencies have consistent code / level / jurisdiction
  • README, SCHEMA.md, and docs/notice-types.md are updated if you added a notice type
  • Commit messages follow conventional-commit format (feat:, fix:, docs:, chore:)

Governance

Patra is maintained by Kreto Systems Inc. for now. PRs are reviewed on a rolling basis. Substantive decisions — new domains, envelope changes, versioning policy — go through a public issue discussion before a PR is accepted.

Long-term, the intent is to move Patra to a neutral foundation once there's enough adapter + consumer ecosystem to justify it. Your PRs help get us there.

Licensing

By contributing you agree your work is released under the MIT license the rest of the project uses. See LICENSE.