Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
115 lines (83 loc) · 5.03 KB

CONTRIBUTING.md

File metadata and controls

115 lines (83 loc) · 5.03 KB

Contributing

Thanks for considering a contribution to @guanzhu.me/arco-cli. The repo is small and the maintainer is a single human — this guide keeps the loop quick for both of us.

Repo layout

src/                       # CLI source (TypeScript, CommonJS output → lib/)
├── bin.ts                 # commander entry point
├── commands/              # one file per `arco` subcommand
├── init/ addPage/ addApi/ # engines that those commands drive
└── utils/                 # cross-cutting infra (exec, cache, clack loader, …)

templates/
├── arco-pro-recommend-full/    # bundled "Arco Pro (Unofficial)" template
└── arco-pro-recommend-simple/  # dashboard-only preset

.verify/app/               # gitignored sandbox where the full template is scaffolded
                           # for smoke + Playwright E2E
docs/                      # English + Chinese deploy guide, README assets
CHANGELOG.md               # keepachangelog format, drives GitHub Releases body
CLAUDE.md                  # architecture notes intended for AI assistants

The CLI is published as @guanzhu.me/arco-cli. The bundled template inside templates/ ships inside the npm package — it's copied verbatim by init/template.ts without a network round-trip.

Getting set up

git clone https://github.com/wn0x00/arco-cli.git
cd arco-cli
yarn install                 # the CLI uses yarn, the template uses npm
yarn build                   # tsc → lib/
node lib/bin.js --help       # local smoke

To exercise the bundled template end-to-end:

node lib/bin.js init my-app --template pro-recommend --skip-install
cd my-app && npm install && npm run dev

Day-to-day commands

What Command
TypeScript watch build yarn dev
Lint yarn lint
Format yarn format
Unit tests (node:test + tsx) yarn test
Single test file node --import tsx --test src/addApi/scaffold.test.ts
Single test by name node --import tsx --test --test-name-pattern="scaffoldApi writes" src/addApi/scaffold.test.ts
Full pre-publish verification yarn verify

yarn verify runs lint + tests + build + npm pack --dry-run. CI runs the same thing across Node 22 + 24 × Ubuntu + Windows, plus a template-build job that scaffolds both presets and runs npm install && npm run build inside them.

Writing changes

Code style

  • TypeScript strict mode in CLI; the template also runs strict + noImplicitOverride
  • ESLint 9 flat config (eslint.config.js)
  • Prettier via lint-staged on commit (auto-format)
  • No emojis in source unless explicitly requested
  • Comments: only when the why isn't obvious — don't restate what the code does

Commit messages

Loosely follow conventional commits, no strict spec:

feat(template): add useUserListQuery hook
fix(template): SPA fallback for Vercel deploys
docs: bilingual deploy guide
chore: 0.11.0                     ← only the version-bump commit

The chore: X.Y.Z commit is what prepublishOnly keys off — keep it as the last commit before tagging.

Tests

  • Engines (addApi/scaffold.ts, addPage/scaffold.ts, etc.) are pure file IO — covered with node:test + node:assert/strict, fixtures land in mkdtempSync(tmpdir()) and clean up in finally.
  • The template's Playwright smoke (templates/arco-pro-recommend-full/e2e/smoke.spec.ts) covers login, search-table mock rows, theme cycle, 404 route. Run with npm run e2e from inside a scaffolded project (one-time npm run e2e:install for Chromium).

Opening a PR

  1. Branch off main (feat/v0.X.Y-thing is the convention used here, but anything readable works).
  2. Make the change + add/update a test.
  3. Run yarn verify locally before pushing.
  4. Open the PR against main. The CI matrix needs to pass before merge.
  5. The maintainer merges with --no-ff to preserve the branch shape, bumps the version, tags, and pushes — the release workflow handles npm + GitHub Release creation.

Release flow

You probably don't need to do this, but for the record:

# After PR merge + version bump
git tag -a v0.11.1 -m "Release v0.11.1"
git push origin main
git push origin v0.11.1

.github/workflows/publish-npm.yml triggers on tags matching v*.*.*, uses npm Trusted Publishing (OIDC, no NPM_TOKEN), publishes with --provenance, and creates a GitHub Release with the body extracted from the matching ## [X.Y.Z] section of CHANGELOG.md. The repository.url in package.json must match the GitHub repo or the provenance bundle is rejected.

Asking questions

  • Bug or concrete feature request → GitHub Issues using the templates
  • Open-ended discussion / "why does X work like Y?" → GitHub Discussions
  • Security report → see SECURITY policy if it exists, otherwise email the maintainer at the address in the npm package metadata

License

By contributing you agree your contribution is licensed under the MIT License.