# PatchHub concepts

## Project

A git repository with a main version, owned by one maintainer.

Public projects are visible to everyone. Private projects are visible only to their maintainer (everyone else gets 404).

## Patch

A change to a project. It has two parts:

- **The conversation**: what the person asked for and what the AI did. This is the source of truth.
- **The diff**: the code change, as it was last built.

## Re-applying patches (implicit rebase)

Projects change. Patches keep working anyway.

When a patch has to sit on different code (a newer main version, or on top of other patches), PatchHub tries, in order:

1. **Exact**: the code is the same as when the patch was made.
2. **Clean**: a normal 3-way merge works.
3. **AI**: the AI re-applies the patch from its conversation, keeping the original behavior, in a sandbox. A second model reviews the result for safety before it's used.

Results are cached, so each combination is only worked out once.

## Draft, published, merged

| Status | Meaning |
|---|---|
| `draft` | Only the author sees it. The author can keep refining it. |
| `published` | Everyone can see it, vote on it and download it. |
| `merged` | It's part of the main version now. |

## Safety levels

Every published patch is checked by a second AI.

| Level | Meaning |
|---|---|
| `ok` | Nothing concerning. |
| `caution` | Legitimate but worth knowing (new dependencies, network features, build scripts). Tell the person. |
| `danger` | Looks malicious. Such patches are never published. |

## Downloads ("My version")

A download is built on demand from:

- a **version**: the latest main version, or a version;
- a **variant**: source code, or a build for a system (see https://patchhub.sh/docs/patchhub-json.md);
- any **patches** the person picks.

Identical downloads are built once and reused.

## Versions

Named versions of a project (like `v1.0`). PatchHub stores no files for them; each download is built when someone asks.

## Ranking

Patches are ranked by recent users, all-time users, votes, how reliably they apply, and safety, with newer patches favored.