diff --git a/AGENTS.md b/AGENTS.md index 3ae583b82bae..e3fd173782ba 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,3 +1,8 @@ +> [!IMPORTANT] +> **RunAnywhere fork:** read [repo-action.md](repo-action.md) before any branch, commit, pull request, +> upstream sync or release. It is binding for every change in this fork and wins over anything below about +> how work lands here. Pull requests target `ra/main`, never `master`. + # Instructions for llama.cpp > [!IMPORTANT] diff --git a/CLAUDE.md b/CLAUDE.md index 302cdeab99cf..3dec9af5ad2c 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1 +1,6 @@ +> [!IMPORTANT] +> **RunAnywhere fork:** read [repo-action.md](repo-action.md) before any branch, commit, pull request, +> upstream sync or release. It is binding for every change in this fork and wins over anything below about +> how work lands here. Pull requests target `ra/main`, never `master`. + IMPORTANT: Ensure you’ve thoroughly reviewed the [AGENTS.md](AGENTS.md) file before beginning any work. diff --git a/RUNANYWHERE.md b/RUNANYWHERE.md index 1ed46e04905f..82523d9a8875 100644 --- a/RUNANYWHERE.md +++ b/RUNANYWHERE.md @@ -1,5 +1,7 @@ # RunAnywhere llama.cpp maintenance notes +Branches, pull requests, upstream syncs and releases follow [repo-action.md](repo-action.md). + This is a direct fork of `ggml-org/llama.cpp`. The RunAnywhere integration branch carries the DeepGrove Maple model architecture and ternary expert graph from `deepgrove-ai/llama.cpp`; it does not wholesale-track that fork. diff --git a/repo-action.md b/repo-action.md new file mode 100644 index 000000000000..601ecfeca8c8 --- /dev/null +++ b/repo-action.md @@ -0,0 +1,74 @@ +# Repo actions: branches, pull requests, upstream syncs, releases + +This is RunAnywhere's fork of `ggml-org/llama.cpp`. Every merge, pull request and +release in this fork follows the rules below, whether a person or an agent does it. +`AGENTS.md` and `CLAUDE.md` are upstream's files. Where they disagree with this file +about how work lands in this fork, this file wins. + +## Branches + +| Branch | What it is | Who writes to it | +|---|---|---| +| `ra/main` | RunAnywhere's integration and release branch, and the default branch. Every fork change lands here. | Pull requests only | +| `master` | An exact mirror of `ggml-org/llama.cpp` `master`. It holds no RunAnywhere commits. | Upstream sync only | +| `/` | One branch per change, for example `siddhesh/pplx-v1.2`. | The author | + +- Never push fork work to `master`. It stays a clean mirror, so it's always clear + which commits are ours: `git log master..ra/main`. +- Never force-push or delete `ra/main`, or any branch a release tag was cut from. +- Branch protection isn't configured yet, so nothing enforces these rules + automatically. Follow them by hand. + +## Pull requests + +- Every change reaches `ra/main` through a pull request, including one-line fixes + and documentation. +- Open one pull request per change. Don't mix a feature, a fix and an upstream + sync in one PR. +- Commit messages are one line: a scope prefix and the concrete change, for + example `llama: read the pplx v1.2 readout at each marker`. +- The PR description says what changed, why, and how it was tested. Give the + build and the real model run with its result. "Builds" alone isn't a test. +- Merge only after the change has been built on macOS (Metal) and Linux (CPU), + and run against the decision and model fixtures it touches. +- Merge feature PRs with **squash** and upstream syncs with a **merge commit** + (see below). Never rebase `ra/main`. +- Upstream's CI workflows run here, but many of their jobs are scoped to + `ggml-org` or need hardware we don't have. A red upstream job doesn't block a + merge. A failure the change itself causes does. + +## Taking upstream changes + +1. Fetch upstream: + `git remote add upstream https://github.com/ggml-org/llama.cpp.git && git fetch upstream --tags`. +2. Fast-forward `master` to `upstream/master` and push it. If `master` can't + fast-forward, something wrote to it; stop and find out what. +3. Branch `sync/` from `ra/main` and merge the upstream tag into it, + for example `git merge b10500`. Merge a release tag (`bNNNNN`), not a moving + `master`. +4. Resolve conflicts in favour of upstream, except in our fork changes. Our + commits are listed by `git log master..ra/main`. +5. Open a PR from `sync/` into `ra/main` and merge it with a merge + commit, so the upstream history stays intact. +6. Check whether any of our commits landed upstream in the meantime. If one did, + drop our copy in the same PR. + +## Releases + +- Tag only a commit on `ra/main` that has been built and tested. Never tag a + side branch. +- Tag names are `runanywhere-b.`, for example + `runanywhere-b10453.9`. `` is the upstream tag `ra/main` was + last synced to, and `` counts our releases on that base. +- Use annotated tags: `git tag -a runanywhere-b10453.9 -m ""`. +- Never move, reuse or delete a pushed tag. The SDK pins tags and SHAs, so a + moved tag silently changes what a shipped build contains. Fix forward with + the next number. +- After tagging, bump the SDK pin (`core/VERSIONS` `LLAMACPP_VERSION` in + `runanywhere-sdks`) in its own PR. +- Record what each release adds in the GitHub release notes for that tag. + +## Fork-specific engineering notes + +`RUNANYWHERE.md` holds the model and backend notes (Maple, Prism `Q2_0`, clef and +the other decision models) and the per-release test checklist.