wehub-resource-sync
426e9eeabd
8.3 KiB
Contributing
Contribute through issues, project boards, discussions, and pull requests against
develop. The repository is agent-operated as well as human-maintained, so the
useful record is the one a reviewer can inspect later: scoped work, current
board state, linked code, and evidence that the real behavior happened.
Start Work
Open an issue before non-trivial work. The issue owns the scope, acceptance criteria, blockers, and evidence plan. Use the existing issue templates when they fit:
Branch from the latest develop with feat/<slug>, fix/<slug>,
docs/<slug>, or chore/<slug>. Always sync before opening or updating a PR:
git fetch origin
git rebase origin/develop
bun install
bun run verify
Keep package-local instructions in view. Read root AGENTS.md or CLAUDE.md,
then the package-local AGENTS.md or CLAUDE.md before touching that package.
GitHub Projects
Issues are work cards. GitHub Projects are the live kanban state and ownership record. Use fields already present on the active board before adding new ones.
Standard flow:
Todo: ready and unclaimed.Claimed: an owner has committed to the card.In progress: code, config, deployment, or shared state is actively being changed.Needs-agent-verify: evidence is posted and another agent should check it.needs-human-verify: agent verification is done or not applicable; a human needs to approve or test.Done: only the managing human or maintainer moves cards here unless the board explicitly says otherwise.
When claiming a card, comment CLAIMING: <scope> on the issue, set the Project
Claimed by field to your lane or agent tag, and keep Status accurate. If the
work needs a shared lever such as production deploys, staging environments, DNS,
secrets, billing, or rollback authority, comment CLAIMING LEVER: <thing>
before touching it and release the lever when done.
Use Discussions for coordination, handoffs, multi-card questions, and noisy
status. Do not make a Discussion the only acceptance record for a task. Durable
decisions belong back in issue bodies, project readmes, AGENTS.md, or package
docs.
Pull Requests
Every change ships through a PR against develop; do not push feature or fix
work straight to develop. Link the issue or Project card the PR resolves.
Keep PRs scoped to one coherent change. If a sweeping mechanical edit touches
many packages, explain why it is mechanical and keep package-specific behavior
changes out of the same PR.
The branch must be rebased on origin/develop before review. Resolve every
conflict, run the relevant package checks, and run bun run verify when the
change is ready for full validation.
Evidence
A reviewer must be able to confirm the real behavior without reading the code. Attach complete, manually reviewed evidence inline in the issue or PR. Do not commit evidence artifacts to the repository.
Required evidence by surface:
- UI changes: before and after full-page screenshots for desktop and mobile, an MP4 walkthrough of the full flow, frontend console and network logs, and backend logs when a server path fires.
- Agent, model, prompt, provider, or action changes: real live-model trajectories with inputs, outputs, tool calls, and results.
- Native, mobile, desktop, or device changes: per-platform screenshots, recordings, logs, and proof the installed build is current.
- Domain changes: the artifacts produced by the change, such as DB rows, memories, scheduled tasks, generated files, wallet balances, on-chain transaction hashes, audio, or device output.
If an evidence type does not apply, keep it visible in the PR and write
N/A - <reason>. Never leave evidence rows blank. Open every artifact yourself
before asking for review; capturing is not review.
The gate is mechanical and fails closed. .github/workflows/pr.yaml runs
scripts/check-pr-evidence.mjs on every PR: a blank/checkbox-only evidence row,
or a bare N/A with no reason, fails the check. A PR whose diff touches a
rendered-UI source file (a .tsx/.css/.svg/.html under packages/app,
packages/ui, apps/app, …) must attach concrete before/after screenshot,
walkthrough-video, and OCR-review artifacts — a link, not N/A — even when the
ui/frontend/native label is absent. Do not try to route around this by
dropping the label; fix the pipeline and capture the evidence.
Before capturing, check your toolchain. Run the doctor; it reports every capture tool (tesseract, ffmpeg, Playwright browsers, GPU/Baidu OCR, Apple Vision, VLM API keys, the claude/codex CLIs) and prints the exact install/start command for anything missing. Install what it flags — a missing tool is a fixable instruction, never a reason to ship without evidence.
bun run evidence:doctor # human report of the capture toolchain
bun run evidence:doctor -- --strict # non-zero exit if a REQUIRED tool is missing
Visual verification is layered and always available. OCR runs the GPU/Baidu
Unlimited-OCR engine when a vision server is up and falls back to tesseract
otherwise; heuristic checks add flat-color/palette and pixel-diff comparisons;
and structured VLM Q&A (vision-qa) reviews screenshots against explicit
questions. When no API key or local server is configured, set
ELIZA_VISION_QA_BACKEND=cli to review screenshots through an already-authed
claude or codex CLI (auto-detected by the doctor) — real token usage is
recorded, so the review is admissible evidence.
Useful commands:
# Real-LLM agent trajectories
packages/scenario-runner/bin/eliza-scenarios run <scenario.ts> --report <out.json>
# E2E UI recordings
bun run test:e2e:record:review
# Full matrix review bundle
bun run test:matrix:review
# App + cloud-UI screenshots; required for packages/app UI changes
bun run --cwd packages/app audit:app
# Native per-platform capture when a native/mobile/desktop surface changes
bun run --cwd packages/app capture:ios-sim -- --issue <n> --slug <s>
bun run --cwd packages/app capture:android-emu -- --issue <n> --slug <s>
bun run --cwd packages/app capture:linux-desktop -- --issue <n> --slug <s>
bun run --cwd packages/app capture:windows-desktop -- --issue <n> --slug <s>
Post videos as MP4 so GitHub renders them inline, screenshots as JPG where
possible, and long logs in a <details> block. Re-capture evidence after
rebasing when develop changes the behavior under review.
Headless agents (no browser, cannot drag-and-drop): upload media to the
dedicated pr-evidence release
and embed the asset URLs — they end in a media extension, render inline via
, and satisfy the evidence gate:
# name files <pr-number>-<artifact>.<ext>, then:
gh release upload pr-evidence 15171-after-desktop.jpg 15171-walkthrough.mp4
# embed in the PR evidence rows:
# 
Never delete assets referenced by an open PR. A worked example of a fully evidenced PR (before/after screenshots, MP4 walkthroughs, OCR readout, vision-QA trajectory with the model named, pixel-diff report, zero-error frontend logs) is #15171.
Security Reporting
The canonical security policy — reporting channel, disclosure window, and
remediation SLAs — is SECURITY.md. In short: report
vulnerabilities privately to security@elizalabs.ai; do not open a public
GitHub issue for a live vulnerability, credential leak, exploit path, or
embargoed dependency issue. Include affected versions or commits, reproduction
steps, impact, and any safe proof of exploitability. Agents that encounter a
secret or suspected vulnerability must stop exposing details publicly and route
the finding to that mailbox or a maintainer-owned private channel.
Security, SOC2, and incident-response reference material lives under
packages/docs/security/. Package-specific security
implementation notes live in the relevant package docs.
License
By contributing, you agree that your contribution is licensed under the repository's MIT license.