Skip to Content
Contributing

Contributing

The engine stays dialect-agnostic because every dialect maps to and from the shared canonical model. Adding an endpoint does not require pairwise converters for existing dialects.

Local setup

Prerequisites: Node ≥ 22.12 and pnpm 12 .

git clone https://github.com/JoaoPedroAS51/rosetta-date.git cd rosetta-date pnpm install
ScriptPurpose
pnpm devBuild the library, then rebuild on source changes.
pnpm buildEmit ESM modules, types, and source maps to dist/.
pnpm playgroundBuild the library, then serve the playground and watch library changes.
pnpm playground:buildBuild the library and playground.
pnpm docs:devServe the documentation site.
pnpm docs:buildBuild the documentation site and search index.
pnpm typecheckType-check the package without emitting.
pnpm lint / pnpm lint:fixLint, and autofix, with the antfu config.
pnpm testRun the suite once.
pnpm test:watchWatch the source suites.
pnpm test:unitRun unit tests.
pnpm test:endpointsRun endpoint conformance, matrix, and round-trip tests.
pnpm test:typesCheck source type assertions.
pnpm test:coverageRun unit and endpoint tests with coverage, gated at 100%.
pnpm test:distBuild, then check plain-Node imports, package metadata, and exports resolution.
pnpm test:types:distBuild, then check the published declarations.
pnpm test:packageBuild, then run both artifact checks in parallel.

Adding a dialect or library

To add a dialect, register it in src/dialects/registry.ts; to add a library, register it in src/libraries/registry.ts and give it a libraryDeltas entry in test/fixtures/oracle.ts. A dialect in an existing syntax family (delimited or directive) is pure data: pick its syntax and map its tokens. A grammar that needs a new family adds one strategy module under src/core/syntax/ and one member to the TokenSyntax union; the parser and renderer stay untouched.

The cross-endpoint suites read a hand-written oracle, test/fixtures/oracle.ts, that maps each canonical to the endpoint’s primary spelling. A new dialect joins them with an expectations entry; TypeScript requires one for every registered dialect.

Then update the documentation so the new dialect or library is discoverable. Keep these pages in sync by hand:

  • Canonical Vocabulary: only if the new dialect or library needs a canonical field that does not exist yet; add the new member here, following the naming grammar below.
  • Dialects: add a row to the index and a page for the new dialect (grammar, literals, aliases, caveats), plus a column in Token Mapping.
  • Libraries: add a row to the index and a page for the new library (its supports subset and any extends tokens).
  • API Reference: list the new export under its entrypoint.

Adding a canonical field

Most dialects and libraries reuse existing canonical fields. Add one only when a token expresses a meaning no member covers. Canonical values follow this grammar:

field/style[/qualifier...]
  • field: the date component (month, hour, week-of-year, …).
  • style: how it is represented (numeric, 2-digit, ordinal, wide, …).
  • qualifier (optional, repeatable): refines the base field/style; its absence is the default form. Examples: iso (ISO week rules), the hour cycle h11 / h12 / h23 / h24, standalone (grammatical context), and presentation refinements such as space-padded (fill) and lower (case).

The member name is the PascalCase of the value’s segments, so name and value stay in lockstep: week-of-year/ordinal/iso ↔ WeekOfYearOrdinalIso, month/wide/standalone ↔ MonthWideStandalone.

Qualifier order is part of a value’s identity, so each meaning has exactly one string and dialects never disagree on a spelling. Order qualifiers by a fixed precedence: identity qualifiers that change the rendered value (iso, the hour cycle, standalone) come first, then presentation qualifiers that only change its surface (space-padded, lower). A blank-padded 24-hour is hour/2-digit/h23/space-padded, never hour/2-digit/space-padded/h23.

Prefer refining an existing field/style with a qualifier over inventing a parallel field. This keeps related meanings grouped and lets conversions share the base. Adding a member is a minor, additive change; renaming or removing one is breaking.

TSDoc conventions

Use a consistent TSDoc structure for dialect and library exports.

Dialect TSDoc documents only the grammar it defines:

  • Scope: the supported token grammar.
  • Literals: how literal text is represented.
  • Rendering: how primary mappings are chosen.
  • Case sensitivity: only when token case changes meaning.
  • @see: official specs or token references.

Avoid mentioning concrete libraries in dialect TSDoc unless the behavior belongs to the dialect itself.

Library TSDoc documents the rendering target:

  • Base grammar: the dialect used by the library.
  • Extensions: tokens added on top of the base grammar.
  • Support model: whether supports is omitted or defines a subset.
  • Runtime behavior: only for runtime requirements outside conversion logic.
  • @see: official library docs.

Wrap code identifiers, plugin names, token names, and package names in backticks.

CI runs lint, typecheck, test:types, test:coverage, and test:package on every pull request. Record user-facing changes with a changeset:

pnpm changeset

Testing

Tests live in packages/rosetta-date/test/, outside src/, and import the package by name (rosetta-date, rosetta-date/dialects, …), which Vitest and TypeScript alias to the source. Each folder is a Vitest project:

FolderProjectScope
unit/unitOne unit’s behavior, in a tree that mirrors src/, plus mechanics the oracle cannot express (unsupported-token reasons, handler context, adjacency)
endpoints/endpointsConformance, the conversion matrix, and round trips across every built-in dialect and library
types/types*.test-d.ts type tests of the public API, grouped by subject

The endpoints suites derive from the oracle in test/fixtures/oracle.ts (each dialect’s expectations, plus each library’s libraryDeltas). An oracle entry gives an endpoint conformance, totality, matrix, and round-trip coverage. Tests reach internals by relative path only when the public API has no equivalent.

Run pnpm test for all three projects, or select pnpm test:unit, pnpm test:endpoints, or pnpm test:types. pnpm test:coverage enforces the 100% threshold for unit and endpoint tests; type assertions do not contribute to runtime coverage.

pnpm test:package builds the library, then runs two checks in parallel: test:types:dist checks type assertions against the published declarations, and test:dist checks a plain-Node import of every entrypoint (test/artifact/smoke.mjs), package metadata with publint  in strict mode, and exports resolution with Are the Types Wrong? . Both commands can also be run separately from the repository root; Turbo builds the library first.

License

MIT  © João Pedro Antunes Silva.

Last updated on