docs: prepare v0.3.0 docs for release - #8
Merged
Conversation
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).
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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.0in both packages,engines.node >=22, peerreactonly), so this PR is documentation only.Changelogs (core + react + docs site)
>=18→>=22on root/core; the react package newly declaresengines.node >=22).buildSnapshotnow clampsinitialSecondsand derivesisCompletedfrom the clamped total.reset(value)as newly-throwing — onlysetSecondsis new in 0.3.0 (reset/construction already threw in 0.2.0).[0.3.0]date to2026-06-27.API docs & examples
examples.md,api-reference.md) that asserted ongetSnapshot()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 failsexpected 2±0 but received 5; fixed snippet passes).TimeProvideris a public export of@timekeeper-countdown/core(it is internal); point totoTimeProvider()from…/testing-utils.Countdownmethods documented as returningboolean— they returnvoid(core-usage.md, core README). The boolean transition result is on the low-levelCountdownEngine.react(>=17.0.0) is a peer dependency, notreact-dom(faq.md,react-integration.md)./#/api-reference→/api-reference).Build fix
</content></invoke>) at the end ofdocs/changelog.mdthat brokenpm run docs:build(and therefore the docs deploy). Pre-existing onmain; scanned all.mdfor 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).