Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ Read [`ai/contributing/curriculum.md`](ai/contributing/curriculum.md) before aut
Ask the maintainer rather than inventing conventions for:

- **Changelog format:** No `CHANGELOG.md` convention is settled. The docs version menu links directly to GitHub Releases.
- **Post-launch MCP and CDN (`tools/mcp`, `tools/cdn`):** Standalone MCP server (`tools/mcp`) and CDN worker/bundle infrastructure (`tools/cdn`) from `next` are optional post-launch additions.
- **MCP and CDN (`tools/mcp`, `tools/cdn`):** Standalone MCP server (`tools/mcp`) and CDN worker/bundle infrastructure (`tools/cdn`) from `next` are iceboxed until requested (`ai/contributing/plan/roadmap.md`).

## Commands

Expand Down
4 changes: 2 additions & 2 deletions ai/contributing/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ Internal records and workflows for developing `native-dates`. Application develo
| Check or record design and process decisions | [`decisions.md`](decisions.md) for the topic index, [`decisions/README.md`](decisions/README.md) before adding or reopening an entry, [`decisions/package.md`](decisions/package.md) (`D1`..`Dn`), and [`decisions/project.md`](decisions/project.md) (`P1`..`Pn`) |
| Check bundle size limits | [`budget.md`](budget.md), checked by `npm run size` |
| Configure GitHub secrets, bots, and Vercel deploys | [`reference/setup.md`](reference/setup.md) |
| View pending and completed launch tasks | [`plan/roadmap.md`](plan/roadmap.md) and [`plan/landed.md`](plan/landed.md) |
| View project roadmap and completed milestones | [`plan/roadmap.md`](plan/roadmap.md) and [`plan/landed.md`](plan/landed.md) |
| Design a class, method signature, or public name | [`naming-lessons.md`](standards/lessons/naming-lessons.md), [`simplicity-lessons.md`](standards/lessons/simplicity-lessons.md), and [`name-public-api.md`](standards/name-public-api.md) |
| Write or update `.d.ts` declarations and `@see` links | [`types.md`](standards/types.md), checked by `npm run types` |
| Write an error message, warning, or log line | [`errors-and-logs.md`](standards/legibility/errors-and-logs.md), checked by `npm run errors` |
Expand All @@ -30,7 +30,7 @@ Internal records and workflows for developing `native-dates`. Application develo
| Decisions index | [`decisions.md`](decisions.md) | Generated topic and chronological index of package decisions (`npm run ai:index`) |
| Decision logs | [`decisions/`](decisions/README.md) | Authoring rules in `README.md`, package rationales in `package.md` (`D1`..`Dn`), and repo/CI process calls in `project.md` (`P1`..`Pn`) |
| Size budget | [`budget.md`](budget.md) | Entry bundles, Brotli ceilings, and per-PR growth rules, updated only by the maintainer |
| Launch plan | [`plan/`](plan/roadmap.md) | Pending rows in `roadmap.md`, completed rows in `landed.md`, and briefs in `plan/scopes/` |
| Project roadmap | [`plan/`](plan/roadmap.md) | Active and iceboxed work in `roadmap.md`, completed milestones in `landed.md`, and briefs in `plan/scopes/` |
| Shared standards | [`standards/`](standards/README.md) | Synced from upstream Semantic repos and not edited directly here |
| Repo workflows | [`workflows/`](workflows/README.md) | Contributor procedures for this repository |
| Technical reference | [`reference/`](reference/architecture.md) | Architecture and external setup docs |
Expand Down
4 changes: 4 additions & 0 deletions ai/contributing/decisions.md
Original file line number Diff line number Diff line change
Expand Up @@ -57,6 +57,8 @@ Active package decisions grouped by area, newest first.

### Plugins, Errors, and Dependencies

- **D18:** `native-dates/helpers/*` stays open for official plugins without semver guarantees (2026-11-20) [L107-L111](decisions/package.md#d18-native-dateshelpers-stays-open-for-official-plugins-without-semver-guarantees-2026-11-20)
- Reopen: third-party consumers couple to `native-dates/helpers/*` in production and break on minor releases.
- **D10:** Error explanations use inline `isDevelopment` checks, and `{ loose: true }` still throws on bad options (2026-11-16) [L59-L63](decisions/package.md#d10-error-explanations-use-inline-isdevelopment-checks-and--loose-true--still-throws-on-bad-options-2026-11-16)
- Reopen: callers building dynamic zone or format inputs from untrusted user text need a non-throwing validation helper.
- **D9:** Core has zero runtime dependencies and trims forked `@semantic-ui/utils` helpers to used branches (2026-11-16) [L53-L57](decisions/package.md#d9-core-has-zero-runtime-dependencies-and-trims-forked-semantic-uiutils-helpers-to-used-branches-2026-11-16)
Expand Down Expand Up @@ -102,3 +104,5 @@ Every package decision (`D1`..`Dn`) in file order.
- Reopen: callers pass endpoints to `.for()` expecting runtime rejection, or expect `.through()` on `DateTime` with inclusive end semantics.
- **D17:** Adjacent unit boundaries use `startOfNext()` and `startOfPrevious()` instead of overloading `next()` and `previous()` (2026-11-19) [L101-L105](decisions/package.md#d17-adjacent-unit-boundaries-use-startofnext-and-startofprevious-instead-of-overloading-next-and-previous-2026-11-19)
- Reopen: callers consistently try unit names in `next()` and `previous()`, or expect numeric weekdays in `startOfNext()`.
- **D18:** `native-dates/helpers/*` stays open for official plugins without semver guarantees (2026-11-20) [L107-L111](decisions/package.md#d18-native-dateshelpers-stays-open-for-official-plugins-without-semver-guarantees-2026-11-20)
- Reopen: third-party consumers couple to `native-dates/helpers/*` in production and break on minor releases.
6 changes: 6 additions & 0 deletions ai/contributing/decisions/package.md
Original file line number Diff line number Diff line change
Expand Up @@ -103,3 +103,9 @@ Reopen: callers pass endpoints to `.for()` expecting runtime rejection, or expec
Overloading `next('month')` conflicts with `DateTime.prototype.next('friday')`, which preserves the time of day (`09:30`) while a unit boundary resets to `00:00`, and callers split on whether `next('month')` means the 1st of next month or `plus(1, 'month')`. Numeric weekdays are rejected in `startOfNext()` so misplaced counts like `startOfNext(2, 'months')` cannot silently resolve `2` as Tuesday.

Reopen: callers consistently try unit names in `next()` and `previous()`, or expect numeric weekdays in `startOfNext()`.

## D18: `native-dates/helpers/*` stays open for official plugins without semver guarantees (2026-11-20)

Narrowing `"./helpers/*"` to the four files `@native-dates/plugins` currently imports would make internal helpers look like curated public API and force a core version bump whenever a future official plugin needs another helper. Omitting `"types"` on `"./helpers/*"` keeps those modules out of editor autocomplete while lockstep `@native-dates/plugins` releases coordinate internal changes.

Reopen: third-party consumers couple to `native-dates/helpers/*` in production and break on minor releases.
17 changes: 9 additions & 8 deletions ai/contributing/plan/landed.md
Original file line number Diff line number Diff line change
@@ -1,12 +1,13 @@
# Landed Milestones

Newest first. When a row in [`roadmap.md`](roadmap.md) merges, move it here with its completion date, user-visible capability, and expected vs. actual Brotli byte impact.
Completed roadmap items, newest first. When a planned feature in [`roadmap.md`](roadmap.md) ships, move it here with its completion date, user-facing summary, and production Brotli delta.

| Date | Row | User-visible outcome | Bundle delta (expected / actual) |
| Date | Milestone | Summary | Brotli delta |
|---|---|---|---|
| 2026-11-20 | North star | Maintainer-authored project goals and tradeoffs in `ai/contributing/north-star.md` | 0 B / 0 B |
| 2026-11-19 | Test suite | Behavioral unit and Chromium Playwright test suites across core, plugins, and polyfill | 0 B / 0 B |
| 2026-11-18 | Size budget | Calibrated 15,000 B Brotli ceiling, 4 PR size tiers, and `Semantic Bundle Bot` PR reporting | 0 B / 0 B |
| 2026-11-17 | Documentation & homepage | English guides, API references, plugin docs, interactive playgrounds, bespoke homepage, and initial 8-locale pass | 0 B / 0 B |
| 2026-11-17 | README | Maintainer-authored root `README.md` | 0 B / 0 B |
| 2026-11-14 | Core package & plugins | `DateTime`, `CalendarDate`, `Time`, `Duration`, `MonthDay`, `YearMonth`, ranges, formatting, and `@native-dates/plugins/{zones,loose,legacy-date}` | baseline (14.06 kB core) |
| 2026-11-20 | North star | Project goals and design principles in [`north-star.md`](../north-star.md) | 0 B |
| 2026-11-19 | Test suite | Unit and Chromium Playwright test suites across core, plugins, and polyfill | 0 B |
| 2026-11-18 | Type declarations | Hand-authored `.d.ts` declarations, JSDoc examples, and `@see` links to `nativedates.dev` | 0 B |
| 2026-11-18 | Size budget | 15,000 B Brotli ceiling and automated pull request size reporting | 0 B |
| 2026-11-17 | Documentation & homepage | Guides, API references, plugin docs, interactive playgrounds, and homepage | 0 B |
| 2026-11-17 | README | Root package `README.md` | 0 B |
| 2026-11-14 | Core package & plugins | `DateTime`, `CalendarDate`, `Time`, `Duration`, `MonthDay`, `YearMonth`, ranges, formatting, and `@native-dates/plugins/{zones,loose,legacy-date}` | 14.1 kB baseline |
27 changes: 12 additions & 15 deletions ai/contributing/plan/roadmap.md
Original file line number Diff line number Diff line change
@@ -1,21 +1,18 @@
# Launch Roadmap
# Roadmap

> status: active pre-1.0 (2026-11-20). Core nouns, plugins, test suite, documentation, bespoke homepage, size budget, and north star are in place (`landed.md`). Remaining 1.0 milestones follow below.
Confirmed features and workstreams planned for `native-dates`. Items land here once agreed on as part of the project. Open a [GitHub issue](https://github.com/Semantic-Org/Native-Dates/issues) to propose new features or discuss design before starting work, and move completed milestones to [`landed.md`](landed.md).

One row per pending milestone. Rows requiring a detailed spec keep a single file in `plan/scopes/<name>.md` covering the agenda and approved spec. When a row finishes, move it from this table to [`landed.md`](landed.md).
Larger features with open design details keep a spec in `scopes/<name>.md`.

- **Autonomy:** `agent` (runs autonomously from a scoped brief), `pair` (maintainer + agent collaboration), or `user` (maintainer-authored).
- **Maturity:** `initial` (open design questions) or `scoped` (concrete implementation plan agreed).
| Feature | Status | Summary |
|---|---|---|
| Consumer agent skills | Ready to build | Publish downstream usage skills in `ai/skills/` with the npm package and serve them at `/skills/<name>.md` and `/llms.txt` on the docs site |
| Benchmark suite | Needs design | Automated browser benchmark suite in `bench/` measuring parsing, arithmetic, formatting, and range iteration across changes |
| Documentation translations | Ready to build | Translated and reviewed guides, API references, and examples across the 8 supported locales |

| Row | Autonomy | Maturity | Scope |
|---|---|---|---|
| Benchmark suite | pair | initial | Port tachometer `bench/` runner and add hot-path operations (`ai/contributing/workflows/extend-bench-suite.md`) |
| User skills | pair | scoped | Author and cold-evaluate downstream skills in `ai/skills/`, then publish in `package.json` `"files"` and expose via `/skills/<skill>.md` and `/llms.txt` (`ai/contributing/workflows/author-user-skill.md`) |
| Type declarations | pair | scoped | Audit `.d.ts` doc comments and add `@see` links to `https://nativedates.dev` once docs anchors settle (`ai/contributing/standards/types.md`) |
| Localization review | agent | scoped | Verify and review localized documentation and homepage copy across enabled locales (`ai/contributing/workflows/docs-i18n.md`) |
| First release | user | initial | Align lockstep versions across workspace packages, tag `v1.0.0`, publish to npm, and deploy production docs |
## Deferred

## Optional Post-Launch Additions
Confirmed direction, waiting on external platform support or demonstrated demand:

- **Standalone MCP and CDN (`tools/mcp`, `tools/cdn`):** Omitted at initial launch. Add under `tools/mcp/` or `tools/cdn/` post-launch only when adoption or distribution calls for them.
- **Retire `@native-dates/polyfill`:** Once baseline Safari ships native `Temporal`, retire `packages/polyfill`, remove playground polyfill shims in `docs/`, and simplify `Intl` epoch stand-ins that exist only for polyfilled `Temporal` objects.
- **Retire `@native-dates/polyfill`:** Once baseline Safari ships native `Temporal`, sunset `@native-dates/polyfill` and drop polyfill-only shims in the docs playground and `Intl` formatting helpers.
- **Standalone MCP server and CDN bundle:** Optional distribution targets if downstream tooling or script-tag usage warrants them.
2 changes: 1 addition & 1 deletion ai/contributing/reference/architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@
| `src/` | `native-dates` | Core date library: `index.js` barrel, one noun class per file (`range.js` holds `Range` and its three subclasses), and category-grouped utilities in `helpers/` |
| `types/` | | Hand-authored TypeScript declarations mirroring `src/`. Their doc comments power editor hover/autocomplete (`@see` links follow [`types.md`](../standards/types.md)) |
| `ai/skills/` | | Downstream agent skills (`*.md` in house form), to be published in `package.json` `"files"` and served via `/skills/<skill>.md` and `/llms.txt` ([`ai-author-context.md`](../standards/ai-author-context.md)) |
| `ai/contributing/` | private | Internal design decisions, bundle budget, launch plan, upstream standards, and contributor workflows |
| `ai/contributing/` | private | Internal design decisions, bundle budget, project roadmap, upstream standards, and contributor workflows |
| `packages/core/` | `@native-dates/core` | Thin scoped re-export of `native-dates` |
| `packages/plugins/` | `@native-dates/plugins` | Opt-in side-effect plugins (`zones`, `loose`, `legacy-date`) in `src/`, with module-augmentation declarations in `types/` |
| `packages/polyfill/` | `@native-dates/polyfill` | Conditional `temporal-polyfill` loader that dynamically imports the polyfill only when `globalThis.Temporal` is absent |
Expand Down