diff --git a/AGENTS.md b/AGENTS.md index 2f7fa9a..7fd38e2 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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 diff --git a/ai/contributing/README.md b/ai/contributing/README.md index 6e7d76a..d983dd7 100644 --- a/ai/contributing/README.md +++ b/ai/contributing/README.md @@ -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` | @@ -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 | diff --git a/ai/contributing/decisions.md b/ai/contributing/decisions.md index b40654a..8bf05b4 100644 --- a/ai/contributing/decisions.md +++ b/ai/contributing/decisions.md @@ -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) @@ -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. diff --git a/ai/contributing/decisions/package.md b/ai/contributing/decisions/package.md index e431dcb..ec845fa 100644 --- a/ai/contributing/decisions/package.md +++ b/ai/contributing/decisions/package.md @@ -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. diff --git a/ai/contributing/plan/landed.md b/ai/contributing/plan/landed.md index 6278acc..ffc6e7e 100644 --- a/ai/contributing/plan/landed.md +++ b/ai/contributing/plan/landed.md @@ -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 | diff --git a/ai/contributing/plan/roadmap.md b/ai/contributing/plan/roadmap.md index 1203bf5..d0247a7 100644 --- a/ai/contributing/plan/roadmap.md +++ b/ai/contributing/plan/roadmap.md @@ -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/.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/.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/.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/.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. diff --git a/ai/contributing/reference/architecture.md b/ai/contributing/reference/architecture.md index 7a22bfd..7cb5bc6 100644 --- a/ai/contributing/reference/architecture.md +++ b/ai/contributing/reference/architecture.md @@ -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/.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 |