Skip to content

docs: add CONTRIBUTING.md#371

Open
interacsean wants to merge 4 commits into
mainfrom
docs/update-contributing
Open

docs: add CONTRIBUTING.md#371
interacsean wants to merge 4 commits into
mainfrom
docs/update-contributing

Conversation

@interacsean

Copy link
Copy Markdown
Contributor

Summary

  • Adds CONTRIBUTING.md documenting the end-to-end contributor lifecycle (issue → branch → develop → quality-check → changeset → PR → review → release), sourced from a previously-drafted (stashed) version.
  • Updated the draft to match current repo state:
    • Added the check-licenses CI workflow (introduced in ci: add check-licenses workflow #353) to the CI table and CI/CD workflow reference.
    • Added the now in-repo api-design-review skill (.agents/skills/api-design-review/) alongside the existing Copilot prompt.
    • Removed the /board-issue command reference — that's a personal Claude Code skill some contributors have installed locally, not something checked into this repo, so the doc now describes filing on the project board generically instead.

Test plan

  • pnpm exec oxfmt --check CONTRIBUTING.md passes
  • Team reviews wording/accuracy of the workflow description

Documents the end-to-end contributor workflow (issue -> branch -> develop
-> quality-check -> changeset -> PR -> review -> release), updated to
reflect the current skills/CI setup: the check-licenses workflow and the
in-repo api-design-review skill, and removing a reference to a personal
board-issue skill that isn't checked into this repo.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
@interacsean interacsean requested a review from a team as a code owner July 9, 2026 01:34
Comment thread CONTRIBUTING.md

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Overall this looks good, but how do we manage the relationship between this and CLAUDE.md?

Some information looks overlapped

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yep good point. We should have CLAUDE.md refer to CONTRIBUTING.md as an include so it is ensured to be read. I think a more human-friendly CONTRIBUTING is useful, as I did not find all the processes clear and intuitive when I came back to work on AppShell a few weeks ago

Comment thread CONTRIBUTING.md Outdated
Comment thread CONTRIBUTING.md Outdated
Comment thread CONTRIBUTING.md Outdated
Comment thread CONTRIBUTING.md Outdated
Addresses review feedback: the doc was re-documenting mutable rules from
add-component/quality-check skills and CI trigger mechanics inline, which
had already drifted (the CI table claimed `push` triggers when both
ci-packages.yaml and ci-e2e.yaml are pull_request-triggered, and the e2e
env var list was missing VITE_TAILOR_AI_GATEWAY_URL). Every section that
duplicated a skill/workflow's content now points at it instead.

Also link CLAUDE.md -> CONTRIBUTING.md so agents are guaranteed to read
the contributor workflow doc, per review discussion.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
@interacsean

Copy link
Copy Markdown
Contributor Author

Thanks both — re-evaluated based on the common thread across these comments: the doc was re-documenting mutable rules (add-component's house rules, quality-check's procedure, CI trigger mechanics, four reference tables) that live authoritatively elsewhere, and it had already drifted as a result — the CI table said push when ci-packages.yaml/ci-e2e.yaml are actually pull_request-triggered, and the e2e env var list was missing VITE_TAILOR_AI_GATEWAY_URL.

Pushed a trim (7ed1d16) that keeps the narrative/lifecycle framing but replaces every restated rule/table with a pointer to its source of truth (.agents/skills/**, .github/workflows/, etc.) so there's exactly one place to update per convention. Also linked CLAUDE.mdCONTRIBUTING.md per @interacsean's comment, so coding agents are guaranteed to load it.

interacsean and others added 2 commits July 13, 2026 14:51
- Fold the duplicated CLAUDE.md positioning note into the intro so CLAUDE
  is characterized once, not in two back-to-back paragraphs.
- Replace the restated pnpm install/dev + version-pinning block in §1 with
  a pointer to README's Development section (the canonical home for
  commands); keep the repo-layout table, which README lacks.
- Drop CLAUDE.md's redundant "Local Development" block (it already points
  to README for commands just above).
- Fix stale fact: packages/core builds with Vite, not tsup.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
@IzumiSy

IzumiSy commented Jul 14, 2026

Copy link
Copy Markdown
Contributor

One more last thing: I found README.md also has mention to development setup, so let's trim that all out, and just add a link to CONTRIBUTION.md.

app-shell/README.md

Lines 30 to 71 in 78b182b

## Development
This project is a monorepo managed with pnpm.
### Prerequisites
This project requires **Node.js 24** (see `engines` in `package.json`; CI runs on Node 24). Some build tooling (`tsdown`) relies on Node 24's native TypeScript config loading — on older versions it falls back to a loader that isn't installed, and the build fails. `engine-strict` is enabled, so `pnpm install` will refuse to run on an unsupported version.
If you use [nvm](https://github.com/nvm-sh/nvm), a `.nvmrc` is provided:
```bash
nvm use # or: nvm install
```
### Setup
```bash
pnpm install
```
### Commands
```bash
pnpm dev # Start all packages in development mode with hot reloading
pnpm build # Build all packages for production
pnpm type-check # Run type checking across all packages
```
### Testing
```bash
cd packages/core && pnpm test
```
### Publishing
This project uses [changesets](https://github.com/changesets/changesets) for version management:
```bash
pnpm changeset:create # Create a changeset describing your changes
pnpm changeset:publish # Build and publish to NPM (automated via CI)
```

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants