Contributing
@bridgee-ai/senna

Contributing

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

Before You Start

Senna is maintained by Bridgee as an independent, curated fork of Cloudflare Kumo. Contributions target the standalone Senna 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/bridgee-ai/senna.git
cd senna
pnpm install
pnpm build

Requirements:

  • Node ^24.12.0
  • pnpm >=10.21.0

External contributors can fork bridgee-ai/senna, push a topic branch to that fork, and open a pull request back to Senna.

Respect the Curated Fork

Cloudflare Kumo is an upstream source, not a branch to merge wholesale. The retained intake script can open one downstream pull request for each new upstream commit; scheduled intake is inactive until a maintainer enables it.

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

Use Names Deliberately

  • Senna is the product.
  • Bridgee is the publisher and maintainer.
  • @bridgee-ai/senna 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 Senna.

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 @bridgee-ai/senna 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 @bridgee-ai/senna 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 @bridgee-ai/senna test

For export or build changes, also run:

pnpm --filter @bridgee-ai/senna 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 @bridgee-ai/senna is a manual, maintainer-controlled operation. Contributors and AI agents must not run version or publish commands.

Open the Pull Request

  • Branch from the Senna repository’s main branch.
  • Use [package] short description, for example [senna] 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.