Skip to content

docs: prepare v0.3.0 docs for release - #8

Merged
eagle-head merged 1 commit into
mainfrom
docs/v0.3.0-readiness
Jun 27, 2026
Merged

docs: prepare v0.3.0 docs for release#8
eagle-head merged 1 commit into
mainfrom
docs/v0.3.0-readiness

Conversation

@eagle-head

Copy link
Copy Markdown
Owner

Summary

Makes the documentation accurate and self-consistent for cutting v0.3.0, so the release can be tagged with no further doc edits. Found by a read-only doc-readiness audit and verified against the source (and git) before fixing — versions/deps were already correct (0.3.0 in both packages, engines.node >=22, peer react only), so this PR is documentation only.

Changelogs (core + react + docs site)

  • Record the breaking minimum-Node bump (>=18>=22 on root/core; the react package newly declares engines.node >=22).
  • Record the single-emit-per-transition behavior change (each transition now emits exactly one snapshot).
  • Record that buildSnapshot now clamps initialSeconds and derives isCompleted from the clamped total.
  • Correct the react entry that listed reset(value) as newly-throwing — only setSeconds is new in 0.3.0 (reset/construction already threw in 0.2.0).
  • Set the [0.3.0] date to 2026-06-27.

API docs & examples

  • Fix the broken deterministic examples (examples.md, api-reference.md) that asserted on getSnapshot() without driving the engine's interval. They now use fake timers (vi.advanceTimersByTime) so the snapshot refreshes before each assertion. Proven with a real red→green test (old snippet fails expected 2±0 but received 5; fixed snippet passes).
  • Remove the false claim that TimeProvider is a public export of @timekeeper-countdown/core (it is internal); point to toTimeProvider() from …/testing-utils.
  • Correct the high-level Countdown methods documented as returning boolean — they return void (core-usage.md, core README). The boolean transition result is on the low-level CountdownEngine.
  • State that only react (>=17.0.0) is a peer dependency, not react-dom (faq.md, react-integration.md).
  • Fix the stale hash-router API Reference link in the react README (/#/api-reference/api-reference).

Build fix

  • Remove a leaked tool-call artifact (</content></invoke>) at the end of docs/changelog.md that broke npm run docs:build (and therefore the docs deploy). Pre-existing on main; scanned all .md for similar artifacts — none other found.

Verification

  • npm run docs:build (VitePress) — passes (failed before the artifact removal).
  • bin/quality-gate.sh --full — green (build + format:check + lint + typecheck + test; core 420, react 18).
  • The corrected example is proven by an actual test (red→green), not asserted.

Make the documentation accurate and self-consistent for cutting v0.3.0,
so the release can be tagged with no further doc edits.

Changelogs (core + react + docs site):
- Record the breaking minimum-Node bump (>=18 -> >=22 on root/core; react
  newly declares engines.node >=22).
- Record the single-emit-per-transition behavior change (each transition
  now emits exactly one snapshot).
- Record that buildSnapshot now clamps initialSeconds and derives
  isCompleted from the clamped total.
- Correct the react entry that listed reset(value) as newly-throwing;
  only setSeconds is new in 0.3.0 (reset/construction already threw in
  0.2.0).
- Set the [0.3.0] date to 2026-06-27.

API docs and examples:
- Fix the deterministic testing-utils examples (examples.md and
  api-reference.md) that asserted on getSnapshot() without driving the
  engine's interval; they now use fake timers (vi.advanceTimersByTime)
  so the snapshot refreshes before each assertion. Verified with a real
  red->green test.
- Remove the false claim that TimeProvider is a public export of
  @timekeeper-countdown/core; point to toTimeProvider() instead.
- Correct the high-level Countdown methods documented as returning
  boolean (they return void) in core-usage.md and the core README.
- State that only react (>=17.0.0) is a peer dependency (not react-dom)
  in faq.md and react-integration.md.
- Fix the stale hash-router API Reference link in the react README.

Build fix:
- Remove a leaked tool-call artifact (</content></invoke>) at the end of
  docs/changelog.md that broke `npm run docs:build` (and the docs
  deploy).
@eagle-head eagle-head self-assigned this Jun 27, 2026
@eagle-head
eagle-head merged commit 716b6bf into main Jun 27, 2026
1 check passed
@eagle-head
eagle-head deleted the docs/v0.3.0-readiness branch June 27, 2026 01:20
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant