Contributing to Electron Stagewright

This project is pre-1.0. The core server can already launch and drive real Electron apps, and first-party plugin packages cover accessibility audits, visual baselines, traces, IPC, network capture, storage, virtual time, native UI, and production checks. Packages are published to npm; feedback through GitHub Discussions and Issues still shapes the next capabilities and documentation.

How we work

Architectural direction is maintained by the maintainers and discussed publicly in GitHub Issues and Discussions before structural changes land.
All discussion happens in GitHub Issues and Discussions (no private channels until the project grows).
Conventional Commits format for commit messages.
Pull requests require: passing CI (pnpm verify), conventional commits, a reasonably-scoped diff.
How the project is governed — roles, decision-making, and the path to becoming a co-maintainer — is documented in GOVERNANCE.md.
How maintainers publish a release is documented in RELEASING.md.

Your first contribution

Fork the repo and create a branch from main.
Make your change; keep the diff reasonably scoped.
Run pnpm verify (lint + typecheck + test + build + format check) until it is green.
Write Conventional Commits messages.
Open a pull request against main with a clear description of what changed and why.

If you are new to the codebase, the most useful first step is often opening a discussion with your use case (see above) before writing code.

Local development

git clone https://github.com/electron-stagewright/electron-stagewright.git
cd electron-stagewright

# Enable Corepack-managed pnpm
corepack enable

pnpm install
pnpm verify  # lint + typecheck + test + build + format check

Dependency updates

Renovate opens a weekly grouped pull request for non-breaking npm maintenance; updates are never automergeable and still require the normal review and CI gates. Major updates are separate, require Dependency Dashboard approval, and must not mix platform upgrades in one pull request. Before merging a major Electron, Playwright, TypeScript, or framework update, run pnpm verify, pnpm matrix, STAGEWRIGHT_E2E=1 pnpm test, and pnpm package:smoke against the proposed version.

Project structure

electron-stagewright/
├── examples/                 # Example Electron apps + scripted scenarios
├── packages/
│   └── core/                 # @electron-stagewright/core — MCP server
│       └── scripts/          # Package-local build helpers
└── .github/workflows/        # CI

Future plugin packages live under packages/plugin-*/ and publish as @electron-stagewright/plugin-*.

Code style

TypeScript strict mode (see tsconfig.base.json).
ESM only — no CommonJS.
Prettier-formatted (run pnpm format).
ESLint with @typescript-eslint.

Public-repo content policy — no internal-planning references

This repository ships only content that is intended to remain public and stable. Internal planning vocabulary stays out of the codebase, documentation, commit messages, PR descriptions, and code comments. Concretely:

Do not reference iteration codes, sprint codes, milestone labels, internal ticket IDs, or roadmap shorthand (e.g. Hito X, Sprint Y, RL-XXX, TIK-XXX, "lands in week N", "by Q3"). If a fix or feature has internal planning context, leave that context in the internal tracker and write the public artifact (code, doc, commit) so it stands alone without it.
If you find an existing reference to internal planning in this repo, fix it inline as part of whatever PR you're working on, no separate ticket needed.

This policy keeps the public artifact legible to people who arrive without prior context, and avoids leaking ephemeral planning vocabulary that loses meaning the moment the milestone closes.

Reporting issues

Use the issue templates. For security vulnerabilities, see SECURITY.md — do not open a public issue.

License

By contributing, you agree your contributions are licensed under MIT (see LICENSE at the repo root).