JSS has no CONTRIBUTING.md at the repo root and no .github/ templates. New contributors (humans AND agents — see #404 / #406) have to reverse-engineer the project's conventions from commit history. A short, opinionated CONTRIBUTING.md would surface what's already de-facto practice.

Suggested shape

Aim for one screen — discoverable, scannable. Not a tutorial; a reference card for the conventions we already follow.

Quick start

git clone https://github.com/JavaScriptSolidServer/JavaScriptSolidServer
cd JavaScriptSolidServer
npm install
npm test          # ~40s, 780+ tests
node bin/jss.js   # run a local pod

Workflow

The project follows a strict issue → branch → PR → merge → pull sequence. No direct commits to gh-pages (the default branch).

1. Open an issue describing the change (or pick an existing one)
2. Branch: git checkout -b issue-<number>-short-slug
3. Commit with a descriptive title + multi-paragraph body explaining the why (see existing history for the cadence)
4. Open a PR linked to the issue
5. Address Copilot review iteratively until clean (the project leans heavily on automated review passes)
6. Squash-merge, delete branch, git pull

Code style

• ESM only, Node ≥ 22 LTS
• No native modules — runs unmodified on Termux, postmarketOS, Cloudflare Workers
• JSDoc on public exports; inline // comments explain why, not what
• Tests via node --test — no test framework dependency
• No build step — source is what ships (see JSS git frontend — web-based git browser for Solid pods #370 / the docs site)

Pull-request expectations

• Every PR includes a test that would have caught the regression
• Full suite must pass before merging (npm test)
• Copilot review cycles are standard; address each finding rather than dismissing
• PR description should explain the user-visible impact, not just the diff

AI / agent contributors

JSS positions as agent-friendly (#404 / #406). Agent-authored PRs are welcome under the same rules as human-authored ones, with one extra norm:

• The PR description should make the change reviewable without re-reading the issue
• Each Copilot finding should be addressed concretely, not deflected

Release

After merge, the maintainer bumps package.json + package-lock.json, npm publish, and deploys to solid.social. Contributors don't need to do this themselves.

License

MIT — same as the existing LICENSE file.

Why this matters

Three audiences benefit:

• Human contributors get a 60-second orientation
• LLMs / agents scanning the repo for "how to contribute" have a canonical answer (per Position JSS visibly as agent-friendly / agentic-native #404 the project's agent-friendliness deserves to be visible)
• Reviewers can point at conventions instead of repeating them across PRs

Refs

• Position JSS visibly as agent-friendly / agentic-native #404 — agentic positioning umbrella
• Update README to surface agentic / agent-friendly positioning #406 — README update (parallel surface-area work)
• JSS git frontend — web-based git browser for Solid pods #370 — JSS Git (the de-facto "no-build" example we point at)