Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,7 @@ Omarchy Mobile runs native Omarchy (Arch Linux ARM, Hyprland, Omarchy's packages
Plans record what already failed and why.
- **Work offline and hand the human a runbook.** Write the code, build it, and run checkpatch, `W=1` and `dt-validate` yourself. Then add a gated runbook to the plan: the commands, Expect/Pass, a **stop condition**, a Rollback and a risk level for each step, read-only steps first. The human runs or approves each step. Record the results in the plan with the date and the kernel release (`uname -r`).
- **Build with an explicit worktree and output directory:** `KERNEL_DIR=~/omamobile-kernel/wt-X KERNEL_OUT=~/omamobile-kernel/out-X bin/omamobile kernel`. Other agents build in parallel, and a shared output directory mixes their builds. On setups from before 2026-10-29 the kernel tree is `~/android/mainline`: use whichever exists (the tools find either).
- **Kernel branches:** one subsystem per branch (`omamobile-<subsystem>`). The human merges branches into the local integration branch `omamobile-int` that the phone runs. Curated, upstream-ready commits go to `omamobile`, the branch published to GitHub. Don't rebase or force-push branches someone else is merging from.
- **Kernel branches:** one subsystem per branch (`omamobile-<subsystem>`). `omamobile` on GitHub is the one source of the release kernel: community pull requests land there as rebase merges, the maintainer's curated, signed-off commits land as a fast-forward of a local release branch built on the current `github/omamobile` (`tools/publish-kernel`), and releases are tags on it (`kernel-<YYYY.MM.DD>`, [RELEASES](docs/RELEASES.md) §8). It is never rewritten or force-pushed. `omamobile-int` is a local integration branch for test kernels only, no longer published and no release source. Don't rebase or force-push branches someone else is merging from.
- **Commit messages:**
- Kernel commits are upstream-style: the subsystem prefix from `git log --oneline <file>`, the why, and the evidence. AI agents never add `Signed-off-by:` (`Documentation/process/coding-assistants.rst`): the human signs off.
- This repository uses an area prefix (`omamobile-gnss: …`, `device-cheetah 0.1.15: …`, `DISPLAY-PLAN: …`), a body that explains why, and the attribution trailer the session asks for.
Expand Down Expand Up @@ -93,7 +93,7 @@ tools/phone-ssh CMD -> run anything; stream files with ssh 'cat > f' < f
| `tools/phone-demo seed\|notify\|clear\|status\|shot\|record` | Fictional demo data for screenshots and videos ([docs/DEMO.md](docs/DEMO.md)): contacts, message threads, a call log and notifications in the session user's omatel stores, backed up first to `/var/lib/omamobile-demo/` and removed exactly by `clear`; `shot` and `record` capture the screen to `logs/demo/`. Changes what the phone shows and sends toasts: announce it, and `clear` before handing the phone back |
| `tools/phone-install-package packages/X` | Build a package on the phone and install it |
| `tools/pr-check [BASE]`, `tests/packages` | The pull-request gate CI runs (`.github/workflows/checks.yml`): identifiers, blobs, AI sign-offs and scripts that parse, then every package's `test/all`; run both before you push (CONTRIBUTING.md §6.5) |
| `tools/kernel-pr-check [-C KERNEL] [--build OUT] [--merge] BASE [HEAD]` | The same gate for linux-omarchy-mobile pull requests: a human Signed-off-by from the author, subsystem prefixes, `checkpatch --strict`, identifiers, and with `--build` the `W=1` builds of touched C files, device trees (new warnings only, against the base) and bindings. `--merge` builds the pull request merged onto BASE, as CI does, and reports a conflict as "rebase needed". Build it in the project container with the Android clang on `PATH` |
| `tools/kernel-pr-check [-C KERNEL] [--build OUT] [--merge] BASE [HEAD]` | The same gate for linux-omarchy-mobile pull requests: a human Signed-off-by from the author, no `Co-Authored-By` (the kernel takes `Assisted-by`), subsystem prefixes, `checkpatch --strict`, identifiers, and with `--build` the `W=1` builds of touched C files, device trees (new warnings only, against the base) and bindings. `--merge` builds the pull request merged onto BASE, as CI does, and reports a conflict as "rebase needed". Build it in the project container with the Android clang on `PATH` |
| `tools/phone-ssh [--fresh\|--stop] CMD` | Run a command on the phone. `OMAMOBILE_SSH_SHARE=1` shares one connection (kept 60 s), so a key that needs a touch per connection asks once rather than about 25 times in `push`. A shared connection survives what happens to new ones, so a check that SSH still works after a USB or firewall step uses `--fresh` (`tools/usbc-deadman` always does) |
| `tools/phone-smoke` | Read-only smoke test of a running phone, with a report for the pull request: boot slot, storage guard, root, kernel health, USB, session, then display, GPU, touch, radios, battery, sound, sensors and cameras as evidence. `--here` on the phone, `--json` for a machine |
| `omamobile-update` (on the phone; `omamobile-omarchy`) | What `omarchy update` runs on the phone: Omarchy's own update with the phone's stand-ins (docs/RELEASES.md §5.4). `check --json` is read-only; an update changes the phone's packages and restarts the shell, so it is the human's call |
Expand All @@ -103,7 +103,7 @@ tools/phone-ssh CMD -> run anything; stream files with ssh 'cat > f' < f
| `tools/phone-provision` | After a fresh install: Google's files from the user's factory image and the phone's own data from the backup. `--fingerprint` copies Trusty's state but never starts the service |
| `tools/build-packages`, `tools/repo-push` | Maintainer only: the signed `[omamobile]` repository, built on the laptop with no phone (needs `keys/`, never committed); the release key's layout is in [RELEASES](docs/RELEASES.md) §10 (`tools/release-key-init`, run once); `tools/repo-publish` publishes to `pkgs.omamobile.org` (development daily from `origin/main`, stable on the maintainer's go). `tools/repo-build` builds on a connected phone instead: an opt-in shortcut for Mesa, Hyprland and libcamera, never a requirement |
| `tools/local-key-init`, `tools/fetch-published`, `--local` | A contributor's port: its own packages signed with a local key in `keys/<codename>/`, the project's published packages fetched with their signatures checked, everything under `out/<codename>/` (RELEASES §10, review lesson L-7). Never the maintainer's `keys/` or `out/repo` |
| `tools/publish-kernel` | Maintainer only: publish `omamobile` to GitHub on a squashed upstream base |
| `tools/publish-kernel [--dry-run] [--tag kernel-YYYY.MM.DD] [BRANCH]` | Maintainer only: fast-forward `omamobile` on GitHub to a local release branch and tag a release on it. Fetches first, never force-pushes, refuses a branch that lacks the published tip (rebase it), merge commits, and commits failing `kernel-pr-check`'s sign-off (`Assisted-by`, not `Co-Authored-By`), prefix, identifier and blob checks. Never run it without the human's go; `--dry-run` first |

Logs from these tools land in `logs/` (gitignored). Quote the relevant lines in the plan, not whole logs, and check them for identifiers first.

Expand Down
2 changes: 1 addition & 1 deletion CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,7 @@ Omarchy Mobile runs native Omarchy on mobile devices: Arch Linux ARM, Hyprland a
- `docker`: kernel builds run in the [`docker/Dockerfile`](docker/Dockerfile) environment (Ubuntu 24.04).
- `adb`, `fastboot` (`android-tools`), `lz4`, `zstd`, `cpio`, `python3`, `ssh`, plus `unzip`, `debugfs` (e2fsprogs), `simg2img`/`lpunpack` and `erofs-utils` for firmware extraction.
- **Android's prebuilt clang and the AOSP boot-image tools.** `bin/omamobile` takes clang from `CLANG_DIR`, and `mkbootimg` and `mkdtboimg.py` from `SRC_DIR` (`system/tools/mkbootimg`, `system/libufdt`). Today these come from a LineageOS checkout (`bin/lineage-ref sync`, about 400 GB). A smaller setup also works: the AOSP `platform/prebuilts/clang/host/linux-x86`, `platform/system/tools/mkbootimg` and `platform/system/libufdt` projects under `~/android` (plus `platform/external/avb` for a device with `AVB_FOOTERS`), with `CLANG_DIR` and `SRC_DIR` set in `omamobile.local.conf`. The initramfs build links against that clang's Android compiler-rt builtins. A lighter toolchain setup would make a good PR.
- **The kernel tree.** Clone [derekross/linux-omarchy-mobile](https://github.com/derekross/linux-omarchy-mobile) to `~/omamobile-kernel/linux`, or set `KERNEL_DIR`. Setups from before 2026-10-29 used `~/android/mainline` (the project began with Android-era names); the tools still find it, and moving is optional. Branch `omamobile-int` is what the phone runs today (every subsystem merged, work in progress included, as one snapshot commit); branch `omamobile` holds the curated, upstream-ready commits and lags behind it. Build `omamobile-int` to match this repository's packages and overlays; base your own kernel work on `omamobile`.
- **The kernel tree.** Clone [derekross/linux-omarchy-mobile](https://github.com/derekross/linux-omarchy-mobile) to `~/omamobile-kernel/linux`, or set `KERNEL_DIR`. Setups from before 2026-10-29 used `~/android/mainline` (the project began with Android-era names); the tools still find it, and moving is optional. Branch `omamobile` is the published kernel and the source of releases (tags `kernel-<YYYY.MM.DD>`, [RELEASES](docs/RELEASES.md) §8): community pull requests and the maintainer's curated work land there, and it only moves forward. Base your kernel work on it. Some cheetah drivers the packages use (AoC, Trusty, the modem) are still being curated into it; the `omamobile-int` branch on GitHub is an old integration snapshot (2026-10-18) that is no longer updated.
- **Google's GPL kernel for your device**, as a reference for registers, clocks and power sequences (manifests at `android.googlesource.com/kernel/manifest`, branches named `android-gs-<family>-…`). The postmarketOS Tensor kernel is a useful second reference.
- **The host side of USB networking:** give the laptop `172.16.42.2/24` on the phone's USB network interface. A NetworkManager profile with a manual address works (see "Host setup" in [NOTES.md](device/cheetah/NOTES.md)).

Expand Down
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -60,7 +60,7 @@ Large trees live outside the repo: the Android-side sources, images and captures
| Path | Contents |
| --- | --- |
| `~/android/omamobile` | LineageOS 24.0 source. Includes Google's GPL Pixel 7 kernel at `out-kernel/google/gs-6.1` |
| `~/omamobile-kernel/linux` | Our kernel repo: branch `omamobile` on mainline v7.3-rc6 (remote `upstream` is Linus's tree), one commit per subsystem so patches can go upstream. Published to [derekross/linux-omarchy-mobile](https://github.com/derekross/linux-omarchy-mobile) by `tools/publish-kernel` (a squashed upstream base, our commits unchanged on top) |
| `~/omamobile-kernel/linux` | Our kernel repo: branch `omamobile` on mainline v7.3-rc6 (remote `upstream` is Linus's tree), one commit per subsystem so patches can go upstream. Published to [derekross/linux-omarchy-mobile](https://github.com/derekross/linux-omarchy-mobile) on a squashed upstream base; pull requests and the maintainer's fast-forwards (`tools/publish-kernel`) move it forward, and releases are tags on it |
| `~/omamobile-kernel/pmos-tensor` | postmarketOS Tensor kernel, for reference |
| `~/android/reference` | Captures from the phone. Contains serial numbers and partition backups: never commit |
| `~/android/factory` | Verified stock factory images, used to restore the phone |
Expand Down
10 changes: 9 additions & 1 deletion device/cheetah/KERNEL-PUBLISH.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,15 @@
<!-- SPDX-License-Identifier: MIT -->
# Publishing the kernel: candidate `omamobile-next` (cheetah / gs201)

Status (2026-10-19): **published.** `omamobile` is on GitHub
Status (2026-11-01): **process changed.** `omamobile` on GitHub is the one
source of the release kernel; `tools/publish-kernel` now only fast-forwards
it from a local release branch built on the published tip, checks sign-offs,
and tags releases (`kernel-<YYYY.MM.DD>`). It no longer replays, squashes or
force-pushes, and `omamobile-int` is no longer published. The commands
below (the replay and force push in 5.4) are history; see
[RELEASES](../../docs/RELEASES.md) §8.

Earlier status (2026-10-19): **published.** `omamobile` is on GitHub
(linux-omarchy-mobile, 146 commits on v7.3-rc6) and moves forward without
rewriting published commits: `tools/publish-kernel` fast-forwards when the
published tip's tree matches a local commit. Community kernel PRs are reviewed
Expand Down
Loading