Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
202 lines (151 loc) · 10 KB

CONTRIBUTING.md

File metadata and controls

202 lines (151 loc) · 10 KB
Raw

Contributing to Tailor Platform AppShell

Thanks for contributing! AppShell is an opinionated React framework for building ERP applications on Tailor Platform. This guide is the end-to-end development workflow — from picking up an issue to a published release.

It's the human-facing walkthrough of how a contribution flows through the repo. Its companion, CLAUDE.md, is the terse orientation doc auto-loaded by coding agents (the architecture map — where things live in the code); it links here for the workflow.

The core idea: one source of truth, many executors

This repo codifies its conventions once — as skills and agents under .agents/skills/ and .github/ — and runs those same conventions through every actor that touches the code (you, Claude Code, Copilot, and the gh-aw bots). When a convention changes, change the skill/agent — not just the code, and not this document: rules, commands, and trigger mechanics live in exactly one place (the skill or workflow file), and this guide only points at them. That keeps this file from drifting out of sync with what actually runs.

TL;DR — the lifecycle

  ┌─ 1. Find/file an issue ........ project board (tailor-inc #15)
  │
  ├─ 2. Branch from main
  │
  ├─ 3. Develop ................... .agents/skills/add-component, catalogue/ (app-shell-patterns source)
  │
  ├─ 4. Quality-check locally ..... .agents/skills/quality-check
  │
  ├─ 5. Add a changeset ........... .agents/skills/create-changeset  (user-facing changes only)
  │
  ├─ 6. Open a PR ................. CI runs automatically; comment `/review` for the API Design Review bot
  │
  ├─ 7. Address review → merge .... resolve High/Medium findings; CI green
  │
  └─ 8. After merge (automated) ... docs-update bot + release workflow (see .github/workflows/)

1. Prerequisites & setup

This is a pnpm + turbo monorepo.

  • Node.js 24 is required (see engines in package.json). engine-strict is enabled, so pnpm install refuses to run on an unsupported version — the plugin packages build with tsdown, whose config loader relies on Node 24's native TypeScript stripping and otherwise fails cryptically. If you use nvm, run nvm use (a .nvmrc is provided).
  • pnpm is pinned via packageManager in package.json — run corepack enable to pick up the right version automatically.
pnpm install     # also wires up git hooks via the `prepare` → lefthook script
pnpm dev         # turbo watch on examples/* → example app at http://localhost:3000

Other common commands: pnpm build (production build), plus the quality checks in §5. This repo publishes via changesets (§6) — you won't run changeset:publish by hand; CI does.

Repository layout

Path What it is
packages/core @tailor-platform/app-shell — the published library (components, hooks, layouts)
packages/vite-plugin @tailor-platform/app-shell-vite-plugin — file-based routing
packages/sdk-plugin Tailor SDK plugin
examples/ vite-app and nextjs-app reference integrations (what pnpm dev runs)
e2e/ Playwright suite + a real Tailor backend definition
catalogue/ Pattern catalogue — source for the generated app-shell-patterns skill
docs/ User-facing documentation (kept in sync by the docs-update bot)
.agents/skills/ Contributor procedures — the source of truth for how to do the work
.github/ Agents, prompts, and workflows (CI + agentic bots)

2. Find or file an issue

Work starts from the team's GitHub project board (tailor-inc, project #15), where each ticket carries a Component field (e.g. Button, Sidebar, Routing, CommandPalette).

  • Search the board for an existing/duplicate ticket before filing a new one. If none exists, draft a new ticket with the Component field set to the affected area (e.g. app-shell).
  • If you use Claude Code, personal skills for searching/creating board tickets (e.g. find-or-create-board-issue) are a convenience some contributors have installed locally — they aren't checked into this repo, so don't assume every contributor has them.

3. Branch & commit conventions

  • Branch from main (the changesets base branch).
  • Commits and PR titles follow Conventional Commits — this is the observed convention in history, e.g. fix(button,badge): …, docs(button): …, ci(agentic-workflows): …. The scope is usually the component or area.

4. Develop using the project's skills

Conventions are encoded as skills under .agents/skills/. Read the relevant SKILL.md (or let your coding agent auto-load it) — these are the authoritative procedures, so this guide won't restate their rules (they'd only go stale here).

  • Adding or changing a UI component → .agents/skills/add-component/SKILL.md (component patterns, styling conventions, public API rules, test expectations).
  • Building pages / picking UI patterns → the app-shell-patterns skill. It is generated from the catalogue/ package (catalogue/src/** is the source) into packages/core/skills/app-shell-patterns/, which is gitignored and shipped to consumers via the npm package. Edit the source in catalogue/ and regenerate with pnpm build (see catalogue/README.md) — never hand-edit the generated skill. CI's check-generated-skills test fails if the two drift, so if you change a component's API, design tokens, or a pattern, update the catalogue source too.

5. Run quality checks locally

Use the quality-check skill (.agents/skills/quality-check/SKILL.md) for the exact commands and order — it's the source of truth for what "clean" means and stays current as tooling changes.

For packages/** changes, also consider running the API Design Review locally before pushing — see .agents/skills/api-design-review/ (Claude Code/CLI agents) or .github/prompts/api-design-review.prompt.md (Copilot).

6. Add a changeset

This repo versions and publishes @tailor-platform/app-shell with changesets. Use the create-changeset skill (.agents/skills/create-changeset/SKILL.md) for bump-type guidance and file format — or just run pnpm changeset:create.

Add one when the change is user-facing: new component/hook/util, behavior-changing bug fix, API change, breaking change, perf improvement, or docs that affect API usage. Skip it for internal-only refactors, dev/build tooling, test-only, and formatting changes.

Dependabot PRs (label dependencies) get a changeset added automatically — you don't write one by hand.

7. Open a PR — what runs automatically

Opening a PR triggers CI (format/lint/test/type-check, e2e where relevant, doc link-checking, license checks) and, on comment, the agentic API Design Review. Exact triggers, paths, and labels live in .github/workflows/ and change over time — check those files rather than trusting a copy here.

Commenting /review on a PR runs the API Design Review bot (.github/agents/api-design-reviewer.md + .github/agents/impact-analyzer.md): it classifies changed packages/** files as public/internal, reviews only changed public code, and posts a severity-sorted verdict. It's multi-round aware — re-runs won't re-flag resolved findings.

8. Review, merge, and what happens after

  • Address the /review bot's High/Medium findings until it returns Approve; ensure all CI checks are green. Low-severity suggestions are non-blocking.
  • After merge to main, automation takes over: a Documentation Updater bot opens a [docs-update] PR from pending changesets, and the Release workflow opens/updates a "Version Packages" PR that publishes to NPM when merged. See .github/workflows/ for the exact triggers.

So a normal feature lands as two or three PRs: your change, an automatic [docs-update] PR, and eventually inclusion in a "Version Packages" release PR.

Reference

Rather than duplicate file-by-file details here (they go stale — see .agents/skills/** and .github/workflows/*.yaml for what's actually authoritative), these are the places to look:

  • .agents/skills/ — contributor procedures (add-component, quality-check, create-changeset, api-design-review).
  • catalogue/ — source for the app-shell-patterns skill shipped to consumers; generated into packages/core/skills/ (gitignored) via pnpm build.
  • .github/agents/ and .github/prompts/ — reviewer personas and IDE-agent prompts.
  • .github/workflows/ — CI and gh-aw agentic workflows (source .md files are compiled to *.lock.yml via gh aw compile; never hand-edit *.lock.yml).
  • CLAUDE.md — architecture orientation for coding agents.
  • README.md — quickstart and development commands.

Tooling & conventions

  • turbo orchestrates tasks (build, dev, type-check, lint, test, fmt).
  • oxfmt (format) + oxlint (lint), versions pinned via the pnpm catalog in pnpm-workspace.yaml. lefthook runs oxfmt on staged files pre-commit.
  • changesets drives versioning and publishing.
  • Supply-chain hygiene: GitHub Actions are pinned by commit SHA. pnpm enforces minimumReleaseAge, exotic-subdep blocking, and lockfile trust (pnpm-workspace.yaml). When adding a dependency or editing a workflow, preserve these (pin SHAs; commit pnpm-lock.yaml).