Contributing
@comhora/clock

Contributing

Set up the Clock repository, follow its curated-fork workflow, and validate a contribution.

Before You Start

Clock is maintained by ComHora as an independent, curated fork of Cloudflare Kumo. Contributions target the Clock directory in comhora/comhora, not the frozen standalone archive or the upstream Cloudflare repository.

For a non-trivial change, open or join an issue before implementation so maintainers can align on API direction and migration impact. Small fixes and documentation changes can go directly to a pull request.

Set Up the Repository

git clone https://github.com/comhora/comhora.git
cd comhora/packages/clock
pnpm install
pnpm build

Requirements:

  • Node ^24.12.0
  • pnpm >=10.21.0

External contributors can fork comhora/comhora, push a topic branch to that fork, and open a pull request back to the monorepo.

Respect the Curated Fork

Cloudflare Kumo is an upstream source, not a branch to merge wholesale. Automated intake is paused while it is adapted to Clock’s nested monorepo path; when re-enabled, it will open one downstream pull request for each new upstream commit.

  • Do not merge or pull upstream/main into Clock’s main.
  • Keep an imported upstream commit intact.
  • Put conflict resolutions and Clock adaptations in separate follow-up commits.
  • Preserve upstream authorship, historical changelog entries, and Cloudflare’s copyright notice.
  • Do not imply that Clock is affiliated with, sponsored by, or endorsed by Cloudflare.

Use Names Deliberately

  • Clock is the product.
  • ComHora is the publisher and maintainer.
  • @comhora/clock is the npm package.
  • Kumo is the upstream project and inherited compatibility namespace.

The physical packages/kumo* paths, Kumo* APIs, KUMO_* constants, and kumo-* semantic tokens remain intentionally. Do not rename them mechanically. New public prose, examples, and package metadata should use Clock.

Pick the Right Location

  • Components: packages/kumo/src/components/
  • Blocks: packages/kumo/src/blocks/
  • Demos: packages/kumo-docs-astro/src/components/demos/
  • Documentation: packages/kumo-docs-astro/src/pages/

Scaffold new components through the repository command:

pnpm --filter @comhora/clock new:component

Demo extraction is name-sensitive: demo filenames and exported functions must end in Demo.

Run the Development Loop

Use separate terminals when changing both the library and docs:

# Terminal 1: package watcher
pnpm --filter @comhora/clock dev

# Terminal 2: docs site
pnpm dev

Implementation expectations:

  • Preserve accessibility semantics and keyboard behavior.
  • Follow existing component patterns for variants, props, and composition.
  • Use semantic kumo-* tokens instead of raw Tailwind color classes.
  • Compose class names with cn(...).
  • Add or update demos and tests with behavior changes.

Validate the Change

pnpm lint
pnpm typecheck
pnpm --filter @comhora/clock test

For export or build changes, also run:

pnpm --filter @comhora/clock build

Changesets and Publishing

Add a changeset for a user-visible change to the published library:

pnpm changeset

Use patch for fixes, minor for backward-compatible features, and major for breaking changes. Documentation-only changes usually do not need a changeset.

Publishing @comhora/clock is a manual, maintainer-controlled operation. Contributors and AI agents must not run version or publish commands.

Open the Pull Request

  • Branch from the ComHora monorepo’s main branch.
  • Use [package] short description, for example [clock] add meter warning variant.
  • Fill in the PR template with review and testing details.
  • Keep commits readable and avoid rewriting commits after review begins.

For deeper implementation guidance, see the repository AGENTS.md, component package guide, and changeset guide.