Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
118 lines (84 loc) · 6.86 KB

CONTRIBUTING.md

File metadata and controls

118 lines (84 loc) · 6.86 KB
Raw

Contributing to Nimbus

AI coding agents have changed how software gets made. The teams that do well adapt their workflows to that change rather than bolting agents onto the old one.

This repo explores what building software with agentic workflows looks like. Treat it as a long-running experiment.

Writing code is no longer the bottleneck — agents handle most of the research, implementation, and first-pass review. Deciding what to build and how is where the leverage is, so that is where we plan to spend human attention and what we ask contributors to help with.

How to contribute

Two paths:

You want to… File it as… Humans Agents
Report a bug or propose a fix an Issue New issue .github/ISSUE_TEMPLATE/
Request a feature or enhancement a Discussion New discussion .github/DISCUSSION_TEMPLATE/feature-request.yml

A well-framed problem is worth more to us than a finished PR. Send the clearest account of the bug, or the strongest case for the feature — the full context that lets us guide an agent through the work. If we take it on, we implement it and try our best to attribute it to you.

Pull requests

Start with an issue or a discussion, not a PR. If we decide to take your bug or feature forward, a maintainer approves you right there in the thread — from then on your pull requests stay open and go through normal review. Until then, PRs from outside the team are closed automatically and pointed back here.

A drive-by AI-generated PR is cheap to write and expensive to review. Deciding what to build, and how, is the part we'd rather do with you up front.

For maintainers

Before you open a PR:

  • Put the change in the right place: framework bugs and plumbing in nimbus-docs, styling and layout in the starter, optional extras in the registry.
  • Edit packages/nimbus-starter-source/, never the templates branch — that's generated, and direct edits get clobbered on the next release.
  • Add a changeset for anything user-facing. Starter edits need a create-nimbus-docs changeset, or the freshness guard fails the PR.
  • For every intentional public API break, apply the breaking-change PR label and add a linked entry to the comprehensive upgrade manifest. Use optional only when every existing site keeps building with the same output without acting; conditional entries stay review-required. Every entry carries manual guidance; add a migration ID, detector, transform, bounded task, and focused fixtures only when maintainers deliberately classify the change as common, mechanical, and canonically detectable. Run pnpm upgrades:check. CI verifies the declaration, pending changeset, and manifest continuity. If a shipped release missed an entry, add it with that release's introducedIn and "backfill": true, as review-required with no migration ID, linked to a pending @cloudflare/nimbus-docs changeset; sites upgrading across that release then see it, and the check lists it for review.
  • Check that pnpm typecheck, pnpm -r test, and pnpm templates:check pass.

For Markdown pipeline changes, extend the small mixed-format fixture in scripts/fixtures/content-integrity/. The template check installs the packed framework into a starter and verifies rendered content across clean and warm builds. Use bounded combinations in unit tests to check preservation of unrelated source across formats, nesting, Unicode, and line endings. A parser-only pass or one production corpus is not sufficient evidence of consumer compatibility.

Local development

Requires Node ≥ 22.12.0 and pnpm 9 (pinned via packageManager, so Corepack fetches it for you).

pnpm install
pnpm dev                 # kitchen-sink dev server at http://localhost:4321 — every component on one page

pnpm dev runs the server in the background and prints its own astro dev stop / astro dev status commands (Ctrl-C won't stop it). Edit files under packages/nimbus-starter-source/src/ and the page hot-reloads.

Working on the CLI, templates, or a real scaffold:

pnpm build:templates     # regenerate the shipped template variants
pnpm templates:check     # generate + scaffold + build one variant end to end
pnpm local               # scaffold a throwaway site against your local packages
pnpm typecheck           # typecheck the whole workspace
pnpm -r test             # every package's tests, incl. the registry tier-invariant guard

Working on the docs site (apps/www):

pnpm --filter "@nimbus/www..." build   # build www plus the workspace packages it depends on
pnpm --filter @nimbus/www run deploy   # deploy; its predeploy rebuilds nimbus-docs first

A bare pnpm --filter @nimbus/www build doesn't rebuild nimbus-docs, so after a version bump it fails with a stale-version error until the package is rebuilt.

CLAUDE.md / AGENT.md carry the deeper architecture notes — you don't need them to run the repo.

Releases

Merging the "chore: bump package versions" PR publishes to npm. Right after it publishes, deploy the docs site:

pnpm --filter @nimbus/www run deploy

nimbus-docs add installs components from the registry the docs site serves, so the two must ship together. Before the deploy, the registry still serves the previous release's components, which may lack what the new package needs. Don't deploy from main between merging a feature and publishing its release, either: the registry would then serve components that need APIs the published package doesn't have yet. add warns when the registry and the project's @cloudflare/nimbus-docs versions differ.

Preview releases

To let someone install and test a PR before it merges, add the pr preview label to it. That triggers the Preview release workflow, which builds @cloudflare/nimbus-docs and @cloudflare/create-nimbus-docs and publishes them to pkg.pr.new — nothing hits the npm registry. A bot then comments on the PR with install commands like:

pnpm add https://pkg.pr.new/@cloudflare/nimbus-docs@<PR#>

The label is removed automatically; re-add it to publish a fresh preview.

Preview packages carry the version the release PR would give them, as a pre-release such as 0.16.0-pr.<number>.sha<sha>, so installing one on a site runs the next release's upgrade entries. A package without a pending changeset gets a patch bump. CI also tests every PR at the version its changesets produce. A branch behind the latest release gets no preview; merge main into it first.

create-nimbus-docs previews scaffold from the PR's own starter, bundled into the preview package and pinned to the matching @cloudflare/nimbus-docs preview. They record no reviewed baseline in nimbus.json.