Contributing
Contributing & Project
Wheels is an open-source project with a small core team and a steady stream of community contributions. This section is for anyone who wants to move the framework itself forward — fixing a bug, adding a feature, improving a guide, shipping a package, or helping triage the issue queue. If you’re building an app with Wheels, the rest of the site is the right place; this section is about working on Wheels.
You’ll learn:
- How the project is governed and who has merge rights
- The four contribution paths and which one fits what you want to do
- Where to find the full PR process, coding standards, and docs-writing conventions
How the project is run
Section titled “How the project is run”Wheels has a core team with merge rights on wheels-dev/wheels, and everyone else contributes through pull requests. Those PRs go through the same review process — one maintainer approval before merge — regardless of who opened them. Core team members open PRs too; nothing lands on develop without review.
The current core team, verified against recent git history on develop:
- Peter Amiri (@bpamiri) — project lead, primary maintainer
- Zain Ul Abideen (@zainforbjs) — maintainer
Core team responsibilities: reviewing and merging PRs, triaging issues, cutting releases, and steering the roadmap. The team is intentionally small so that review throughput stays high and architectural direction stays coherent. Community contributors expand both the reach of the framework and the pool of expertise — a recent develop history shows PRs from dozens of contributors across models, middleware, CLI, and docs.
If you’re unsure whether an idea will be accepted, open an issue first and tag @bpamiri or @zainforbjs. It’s cheaper than writing a PR that gets closed.
Code of conduct
Section titled “Code of conduct”Participation in Wheels spaces — GitHub, discussions, issues, PRs — is governed by the Contributor Covenant Code of Conduct. Report incidents to conduct@wheels.dev. Reports are reviewed promptly and confidentially.
Four ways to contribute
Section titled “Four ways to contribute”Pick the one that matches what you want to do. Every path is welcome and every path has a review process.
Bug fixes, new features, performance work, refactors. If you’re changing files in vendor/wheels/ or adding framework behaviour, this is your path. Start from an issue — either one that already exists or one you open to describe the problem before you write code. Breaking changes and anything touching core functionality should be discussed in an issue before a PR lands. See Pull Requests for the full flow and Coding Standards for style and structure rules.
Documentation
Section titled “Documentation”Fixing a typo, clarifying a guide, adding a missing example, filling a gap. Docs PRs are exempt from the test-writing requirement but still go through review. The Writing Documentation guide covers the Diátaxis split (tutorial / how-to / concept / reference), the verify-docs harness that compiles every tagged code block, and the style rules that keep the site consistent.
Packages
Section titled “Packages”First-party packages are standalone repositories under wheels-dev/ (e.g. wheels-sentry, wheels-hotwire), indexed by the wheels-dev/wheels-packages registry. Good candidates: opt-in integrations (error trackers, UI toolkits, front-end frameworks) that don’t belong in the framework core. A new package needs a package.json manifest, tests in <package>/tests/, and a docs page under Digging Deeper. See Packages for the manifest shape and activation model; submit your package to the registry per its CONTRIBUTING.md.
Issue triage
Section titled “Issue triage”Reproducing bug reports, labelling issues, closing duplicates, pointing people at existing answers. This is high-leverage work — one person triaging an hour a week keeps the queue healthy for everyone. No special permissions needed; start by commenting on open issues. The core team will add the triage label to contributors who are consistent.