# Contributing

How to build and test the open-source Repowise repository, find something to work on, claim an issue, and open a pull request.

Repowise is developed in the open at
[github.com/repowise-dev/repowise](https://github.com/repowise-dev/repowise)
under [AGPL-3.0](https://docs.repowise.dev/licensing). The full guide is
[CONTRIBUTING.md](https://github.com/repowise-dev/repowise/blob/main/.github/CONTRIBUTING.md);
this page is the short version.

## Build and test

You need Python 3.11 or newer, Node.js 20 or newer,
[uv](https://docs.astral.sh/uv/), and Git.

```bash
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 6,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](https://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](https://docs.repowise.dev/mcp/overview):

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

| Directory | What it holds |
|---|---|
| `packages/core` | Ingestion, analysis and the documentation generator |
| `packages/cli` | The `repowise` CLI |
| `packages/server` | The API and the MCP server |
| `packages/web`, `packages/ui` | The local dashboard and its shared components |
| `packages/types`, `packages/api-client` | Shared TypeScript types and the typed API client |
| `packages/vscode` | The [VS Code extension](https://docs.repowise.dev/getting-started/vscode) |
| `tests/` | `providers/`, `unit/` and `integration/` |

## Find something to work on

- **[Good first issues](https://github.com/repowise-dev/repowise/labels/good%20first%20issue)**
  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](https://github.com/repowise-dev/repowise/labels/help%20wanted)**
  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](https://docs.repowise.dev/intelligence/refactoring) 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](https://docs.repowise.dev/installation/languages).

## 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](https://www.conventionalcommits.org/), 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:

   ```bash
   uv run repowise risk main..HEAD           # size percentile and the touched files' fix record
   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](https://github.com/repowise-dev/repowise/issues).
- Questions and discussion: [Discord](https://discord.gg/cQVpuDB6rh).
- Security vulnerabilities: follow
  [SECURITY.md](https://github.com/repowise-dev/repowise/blob/main/.github/SECURITY.md),
  not a public issue.

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