Contributing

Repowise is developed in the open at github.com/repowise-dev/repowise under AGPL-3.0. The full guide is CONTRIBUTING.md; this page is the short version.

Build and test#

You need Python 3.11 or newer, Node.js 20 or newer, uv, and Git.

git clone https://github.com/repowise-dev/repowise.git
cd repowise

uv sync --all-packages      # every Python package in the uv workspace
npm install                 # web frontend dependencies
npm run build               # build the web frontend
uv run repowise --version   # the CLI runs from source

uv run pytest tests/providers/ tests/unit/   # the two suites CI runs on every pull request
npm run lint
npm run type-check

tests/providers/ is the suite people forget, and CI does not, so run both.

Python is linted with ruff check ., which is the only Python check CI runs. Do not run ruff format .: the repository is not kept under the formatter, and the resulting diff buries your change.

Find your way around#

The repository has about 3,000 files. Use Repowise on itself instead of reading it front to back:

• Without installing anything, the public index at repowise.dev/repo/repowise-dev/repowise re-indexes on every push and has the overview, architecture, code health, owners and decisions.
• Locally, index it with no API key and point your agent at the MCP tools:

uv run repowise init --no-prose -y   # graph, git history, health, decisions; no model, no spend
uv run repowise serve                # local dashboard and API

Find something to work on#

• Good first issues are reserved for people making their first contribution to the project. If you have already had work merged, leave them for someone new.
• Help wanted marks scoped work for contributors who already know the codebase.
• The refactoring backlog on the public index lists the concrete plans Repowise computes for its own code, each with its blast radius. See Refactoring intelligence for how they are made.
• Language support. A new language is a LanguageSpec, a tag, a .scm query file, a parser config and the grammar dependency, with no change to the parser core. Current coverage is on Language support.

Claim before you build#

Issues go to one person at a time, so two people do not build the same fix.

• Comment on the issue that you are taking it. The comment reserves it from the moment you post, even before a maintainer assigns it.
• Read the thread first. If someone has already said they are taking it, it is theirs.
• Only the person who claimed an issue opens the pull request for it.
• A one-line comment unclaims it. A claim expires after two weeks of silence.

Asking about scope before you claim is welcome, and asking is not claiming.

Before you open a pull request#

1. Branch from main with a prefix: feat/, fix/, chore/ or refactor/.

2. Write Conventional Commits, for example fix(health): bound duplication detection.

3. Run the tests above, then check your change with the tool itself. None of these is a gate, and none calls a model:

   uv run repowise risk main..HEAD           # defect risk of your branch, 0 to 10
   uv run repowise impacted-tests --staged   # the tests your diff exercises
   uv run repowise health --file <path>      # did the file you touched get worse?

4. Keep the pull request to one change, describe what and why, and reference the issue. Every pull request needs one code owner approval.

Where to talk#

• Bugs and feature requests: GitHub Issues.
• Questions and discussion: Discord.
• Security vulnerabilities: follow SECURITY.md, not a public issue.

By contributing, you agree that your contribution is licensed under AGPL-3.0.