Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
22 commits
Select commit Hold shift + click to select a range
d75d9f2
tools/pkg-version: count package versions from main's history
robotosaith Nov 12, 2026
186ac97
packages: pkgver from tools/pkg-version
robotosaith Nov 12, 2026
cbb2f23
CONTRIBUTING, AGENTS, RELEASES: versions are counted, not bumped
robotosaith Nov 12, 2026
cee48bf
tools/pkg-version: refuse a version file that doesn't parse
robotosaith Nov 12, 2026
6226896
build-packages: a package without a version is skipped, not the run
robotosaith Nov 12, 2026
f912cd2
packages: the version file a package installs holds its own version
robotosaith Nov 12, 2026
0d48255
tools/pkg-version: edits not committed yet are their own version
robotosaith Nov 12, 2026
e6e22ba
tools/repo-publish: never publish a test build
robotosaith Nov 12, 2026
9af97d1
tools/release: ask for a commit under the device package, not a bump
robotosaith Nov 12, 2026
a4f1fd1
CONTRIBUTING, AGENTS, RELEASES: how versions went from written to cou…
robotosaith Nov 12, 2026
025a4e6
tests: release-signing and pinned-packages copy pkg-tar.sh and pkg-ve…
robotosaith Nov 12, 2026
e289d29
tools/pkg-version: the count starts at the package's own opt-in
robotosaith Nov 12, 2026
e10d395
omamobile-device-cheetah: keep a written version for its boot files
robotosaith Nov 12, 2026
1984e88
omamobile-reviewer: leave the review rules as on main
robotosaith Nov 12, 2026
e5a9695
Merge remote-tracking branch 'origin/main' into pkg-version-from-git
robotosaith Nov 12, 2026
8497dcb
tests/release: main's again, with tools/release
robotosaith Nov 12, 2026
f58c8ba
Merge remote-tracking branch 'origin/main' into pkg-version-from-git
robotosaith Nov 14, 2026
7944227
tools/pkg-version: a commit a merge brought in is a branch build
robotosaith Nov 14, 2026
b338a33
build-packages: a counted version comes from tools/pkg-version
robotosaith Nov 14, 2026
d02f307
RELEASES: no example numbers in §7.1, and a respin from a branch
robotosaith Nov 14, 2026
2844b3b
Merge remote-tracking branch 'origin/main' into pkg-version-from-git
robotosaith Nov 15, 2026
a4d2674
omamobile-install-link: count its version like the other packages
robotosaith Nov 15, 2026
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
2 changes: 1 addition & 1 deletion .github/pull_request_template.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ partition contents: use placeholders such as <SERIAL>.
- [ ] `tools/pr-check origin/main` passes
- [ ] `tests/all` passes
- [ ] `tests/packages` passes (or the packages I touched: ...)
- [ ] Each changed package has its `version` bumped, and the new version is in the commit subject
- [ ] No package `version` bumped: the version is counted at merge (`tools/pkg-version`, CONTRIBUTING §6.3)
- [ ] Commits have area prefixes and bodies that say why; any AI help is a `Co-Authored-By:` or `Assisted-by:` trailer, never a `Signed-off-by:`

## On the phone
Expand Down
4 changes: 4 additions & 0 deletions .github/workflows/checks.yml
Original file line number Diff line number Diff line change
Expand Up @@ -59,6 +59,10 @@ jobs:
node --version
fi
- uses: actions/checkout@v5
with:
# The packages' versions are counted from main's history
# (tools/pkg-version), and origin/main is the line they count on
fetch-depth: 0
- name: A normal user (some tests check what a user may not do)
run: |
useradd -m ci
Expand Down
3 changes: 3 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -8,3 +8,6 @@ logs/
# Python bytecode from running package code in place
__pycache__/
*.pyc

# A package version worked out for a build without git (tools/lib/pkg-tar.sh)
packages/*/.pkgver
8 changes: 5 additions & 3 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,7 @@ Omarchy Mobile runs native Omarchy (Arch Linux ARM, Hyprland, Omarchy's packages
- **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.
- This repository uses an area prefix (`omamobile-gnss: …`, `omamobile-device-cheetah: …`, `DISPLAY-PLAN: …`; no package version, which is counted at merge), a body that explains why, and the attribution trailer the session asks for.
- **Reviewing pull requests:** use the `omamobile-reviewer` agent (`.claude/agents/omamobile-reviewer.md`), one PR (or a few related ones) per run. It reads the review lessons ([docs/review/LESSONS.md](docs/review/LESSONS.md) is their index, the entries are in `docs/review/lessons/`), runs `tools/pr-check` or `tools/kernel-pr-check`, and returns a verdict, a draft comment and candidate lessons. Nothing is posted until the maintainer says so; confirmed lessons (and corrections, when a review was wrong) are added to the lesson files in a `docs/review: …` commit, so the next review knows them.
- **Commit only your own files when others have uncommitted work**, with a temporary index:

Expand All @@ -57,7 +57,8 @@ Omarchy Mobile runs native Omarchy (Arch Linux ARM, Hyprland, Omarchy's packages
```

This leaves other people's staged and unstaged changes alone.
- **Moving a feature from bring-up into a package:** bump the package `version`, enable nothing that isn't hang-safe, and delete the bring-up files from `/etc/modprobe.d` on the phone (`omamobile-*-bringup.conf`, and any hand-copied package file). A file in `/etc/modprobe.d` replaces the package's `/usr/lib/modprobe.d` file of the same name, so a stale `omamobile-aoc.conf` there hid the package's new blacklist.
- **Package versions are counted, never written** ([CONTRIBUTING](CONTRIBUTING.md) §6.3): don't change a package's `version` file except to start a new series, and don't put a version in a commit subject. A doc or plan written in a pull request can't know the number its change will ship as: name the pull request or the commit, and add the number (`tools/pkg-version --history <package>`) once `main` has it. Versions already in the docs (`omamobile-modem` 0.1.15+) are published ones and stay right. The packages built from another project's release (Mesa, Hyprland, libcamera and the others whose PKGBUILD sets `pkgver` itself), `linux-omamobile`, `omamobile-keyring` and `omamobile-device-cheetah` (its boot files get a version only after they have booted on the 7 Pro) still carry hand-written versions.
- **Moving a feature from bring-up into a package:** enable nothing that isn't hang-safe, and delete the bring-up files from `/etc/modprobe.d` on the phone (`omamobile-*-bringup.conf`, and any hand-copied package file). A file in `/etc/modprobe.d` replaces the package's `/usr/lib/modprobe.d` file of the same name, so a stale `omamobile-aoc.conf` there hid the package's new blacklist.
- **Kernel releases change with every push** (`7.3.0-rc6-omamobile-push1-NNNNN-g<sha>`). `bin/omamobile push` runs `modules-push` when the tarball's checksum differs. Without its modules a new kernel boots without its drivers, the GPU among them. `modules-push` replaces `/usr/lib/modules/<release>` as a whole; on the 9a that once took a hand-installed panel driver with it, and the display stayed on the boot logo. It now refuses when the folder holds modules added or swapped by hand since the last push (it records what each push installed in `.omamobile-modules.sha256`), and `OMAMOBILE_MODULES_REPLACE=1` overrides that, wiping them. Pin a daily release whose folder carries hand-installed modules (`/usr/lib/modules/.omamobile-pinned`), and keep a copy before overriding (`tar -C /usr/lib/modules -cf … <release>`).
- **Stop the modem before a `push` or a `reboot-to`.** `push` ends in `reboot-to`, a raw reboot syscall that stops no unit, so `omamobile-modem.service` never runs its clean stop and its `modem-up` marker stays. On the 7 Pro, where the modem starts at boot (device-cheetah 0.1.43+), the next boot counts that as an unclean end ("ended without a clean stop: a hang or a reset"); from `omamobile-modem` 0.1.19 it starts the modem all the same (before, it skipped the modem once), and a second such end before a clean stop holds it off until `omamobile-modem-start --retry`. So a skipped stop no longer costs a boot's modem, but it uses up the one unclean end the guard allows. This happened on 2026-11-08 after a `reboot-to bootloader` taken to charge a flat battery. So run `systemctl stop omamobile-modem` first, as part of the reboot the human said yes to; a reboot that needs no reason can be `systemctl reboot` instead, which stops it. The stop powers the CP off (one recovered UFS error-handler pass, as any reboot with the modem up costs) and, with the NV overlay on, captures its writes. For now it takes about 40 s and ends as "failed", with the CP's power-off logged as a crash; the marker is still removed ([#532](https://github.com/derekross/omarchy-mobile/issues/532)). This is not the restart the modem notes below forbid: nothing starts the modem again before the reboot. From `omamobile-modem` 0.1.21, with a device package whose `reboot-to` notes the boot it ends ([#403](https://github.com/derekross/omarchy-mobile/pull/403)), the next boot doesn't count a marker from that boot, so a `reboot-to` no longer uses up the unclean end (one already counted stays counted); the CP's ordered power-off and the NV capture still come only from the unit's stop, so the rule stands. [MODEM-PLAN](device/cheetah/MODEM-PLAN.md) M4.6b

Expand Down Expand Up @@ -105,6 +106,7 @@ tools/phone-ssh CMD -> run anything; stream files with ssh 'cat > f' < f
| `packages/linux-omamobile/stage KERNEL_OUT`, `tools/stage-boot-files` | Stage a kernel build for the kernel package, and a device's dtbo, overlays and release initramfs for its device package (gitignored `prebuilt/`, `boot-files/`); laptop only, no phone |
| `omamobile-omarchy-patches status\|verify\|apply` (on the phone) | The Omarchy patch series: what is applied, already upstream or failed; `apply` re-applies it all or nothing (the pacman hook does this after every Omarchy upgrade). Log: `/var/log/omamobile/omarchy-patches.log` |
| `tools/build-packages`, `tools/build-rootfs` | aarch64 packages (signed, `out/repo`) and the root image, built on the laptop in an Arch Linux ARM container (qemu-user); no phone |
| `tools/pkg-version PACKAGE`, `--commit PACKAGE VERSION` | A package's version, counted from `main`'s history (the series in `version`, then one per commit touching the package; off `main`, `.<n>.g<commit>` on top; edits not committed yet, `.d<tree>`), and the commit a version was built from. Read-only. The build tools put it in their copies as `.pkgver`; it refuses a shallow clone |
| `tools/install-guided`, `tools/factory-index` | The guided install ([INSTALL-GUIDED](docs/INSTALL-GUIDED.md)), run twice on the 7 Pro as reinstalls; release bundles ship it with `phone-smoke`, `factory-index` and `camera-requirements.txt` under their signed checksums, as `bash install --guided` in the bundle's folder (the bundle's `install` hands `--guided` on to it), which needs no option there: it reads the bundle's own images, root image, descriptor and tools. It runs `install-phone`, the USB connection (`nmcli`, with consent: a plain link, no sharing), `nv-backup`, `phone-provision` and `phone-smoke` in order, resuming from its record in `~/.local/state/omamobile-install/` (which holds a digest of the phone's serial: never commit or share it). It sends `adb reboot bootloader` and a restart, adds a NetworkManager profile, downloads Google's factory image from `https://dl.google.com/` once the owner has accepted Google's terms in it (several GB into `~/.cache/omamobile-install/factory/`; the project hosts none of Google's files) and ends in the installer's writes, so never run it without the human's go, and never answer its terms question, its "already running Omarchy Mobile?" question or its "Install again from the start?" question for the owner; `--dry-run` reads the phone in fastboot and writes nothing, `--status` reads only the record. After the write it asks the phone that answers over SSH which one it is and stops for any other. `factory-index` keeps `device/<codename>/factory-builds.json` (metadata of Google's factory builds, never their files) and needs no phone |
| `tools/install-phone` | The installer: fastboot checks, the owner's answers into a local image copy, then only slot B's images and `userdata`. Asks the human to type the codename; `--dry-run` first. Never run it without the human's go |
| `tools/nv-backup DIR`, `--check DIR` | The read-only backup of the radio and calibration partitions (the descriptor's `NV_PARTS` and `NV_BACKUP_EXTRA`) over USB SSH, found by `PARTNAME`, refused unless all are read-only and unmounted, each copy verified against a second read on the phone; `--check` is the checksum check of section 1 against such a backup. The output holds the IMEI: never commit or share it |
Expand Down Expand Up @@ -220,7 +222,7 @@ Each entry gives the gotcha, then the reason or the fix. Details are in the link
- pointer handlers declared directly on a window get no events, so put them on an Item inside it;
- Qt 6.12's `QtQuick/Color` shadows Omarchy's `Commons.Color`, so import `qs.Commons as Commons`.
- **pacman.conf order on aarch64:** `[omamobile]`, then `[omarchy]`, then Arch Linux ARM's repositories, so our Mesa and Omarchy's builds win. Use `omarchy update`, not `pacman -Syu`: on the phone it hands over to `omamobile-update` (patch 0012), which refuses a wrong order, low battery, another kernel or a bootloader package (`linux-omamobile` passes only when `omamobile-boot-update preflight` does), skips Snapper, the AUR and gum prompts, and holds boot-related migrations ([RELEASES](docs/RELEASES.md) §5.4).
- **Omarchy upgrades overwrite our Omarchy patches;** `omamobile-omarchy`'s pacman hook puts them back (all or nothing, from Omarchy's own files). Two families are selected by the installed Omarchy version: 4.5, which `[omamobile]` holds phones at since 2026-11-11 (`rootfs/packages.pinned`), uses `packages/omamobile-omarchy/patches/` (`patches/omarchy` links only to that family); a phone still on 4.0.6 uses `packages/omamobile-omarchy/legacy-4.0.6/` until its next `omarchy update`. Fixes go in `patches/`; `legacy-4.0.6/` takes only what a phone needs to get through that update. Bump the package version and make the selected family apply with `--fuzz=0` on the Omarchy the phone runs: `packages/omamobile-omarchy/test/all` applies it to the real aarch64 package. A patch Omarchy has absorbed is reported as upstream: drop it.
- **Omarchy upgrades overwrite our Omarchy patches;** `omamobile-omarchy`'s pacman hook puts them back (all or nothing, from Omarchy's own files). Two families are selected by the installed Omarchy version: 4.5, which `[omamobile]` holds phones at since 2026-11-11 (`rootfs/packages.pinned`), uses `packages/omamobile-omarchy/patches/` (`patches/omarchy` links only to that family); a phone still on 4.0.6 uses `packages/omamobile-omarchy/legacy-4.0.6/` until its next `omarchy update`. Fixes go in `patches/`; `legacy-4.0.6/` takes only what a phone needs to get through that update. Make the selected family apply with `--fuzz=0` on the Omarchy the phone runs: `packages/omamobile-omarchy/test/all` applies it to the real aarch64 package. A patch Omarchy has absorbed is reported as upstream: drop it.
- **`environment.d` can't unset a variable:** `VAR=` with an empty value is a syntax error, and the generator skips the line silently, so the old value stays. Set an explicit value instead (`omamobile-shell` uses `none`).
- **GeoClue answers no client until an authorization agent is registered for the caller's user,** and queues the call with no timeout, so every client just times out. `omamobile-gnss` runs GeoClue's demo agent as a user unit; app allow-list entries skip only the agent's question, not the agent.
- **Firewall changes** (ufw is on): arm `systemd-run --on-active=90 /usr/bin/ufw disable` first, then check with a fresh SSH connection (`tools/phone-ssh --fresh`).
Expand Down
3 changes: 2 additions & 1 deletion CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -306,7 +306,8 @@ Findings that matter beyond one subsystem go into `device/<codename>/NOTES.md`,

### 6.3 This repository

- **Commit subjects** name the area, then say what changed: `omamobile-gnss: package GNSS with location on demand`, `device-cheetah 0.1.15: reconnect USB after a replug`, `shell 0.1.17: …`, `DISPLAY-PLAN: D3b-1b result, …`, `NOTES: …`. When a commit changes a package, bump its `version` file and put the new version in the subject.
- **Commit subjects** name the area, then say what changed: `omamobile-gnss: package GNSS with location on demand`, `omamobile-device-cheetah: reconnect USB after a replug`, `DISPLAY-PLAN: D3b-1b result, …`, `NOTES: …`. No package version: it is counted when the change lands on `main`.
- **Package versions are counted, not written.** Leave `version` alone: [`tools/pkg-version`](tools/pkg-version) gives every commit on `main` that touches a package the next number of its series (the first two numbers in `version`), so two merges can't ship one number. A build off `main` gets `<main's version>.<your commits>.g<commit>`, which `pacman` orders between `main`'s builds, and edits not committed yet add `.d<tree>`, a new version for each edit, so `tools/build-packages` rebuilds them without `--force`. Change `version` only to start a new series (`0.2` to `0.3`); a third number there is read as a floor and nothing else, so an old-style bump does no harm. A dependency on a change that isn't on `main` yet can't name its number: depend on a version `main` has already shipped, or on a name the other package `provides`. The same goes for docs: name a version only once `main` has shipped it (`tools/pkg-version --history <package>` lists them), and the pull request until then. Packages built from another project's release (Mesa, Hyprland, libcamera and the others whose PKGBUILD sets `pkgver` itself), `linux-omamobile`, `omamobile-keyring` and device packages that ship boot files (`OMAMOBILE_BOOT_FILES` in `install`: `omamobile-device-cheetah`, whose version the maintainer writes after the boot files have booted on the 7 Pro) keep hand-written versions: raise `pkgrel` (or the kernel package's `version`, which is its `pkgrel`) for a packaging change. On a fork whose own `main` is behind, count against this repository's: `git fetch upstream`, then `OMAMOBILE_MAIN_REF=upstream/main`, or a test build sorts below the published package. How the project moved from written to counted versions, and what happens to pull requests opened before, is in [RELEASES](docs/RELEASES.md) §7.1.
- **Bodies** explain the why and what was tested. Wrap at 72 columns. If an AI assistant co-wrote the commit, end with a `Co-Authored-By:` trailer, as the history does.
- **Every file has an SPDX header** (§7).
- **Describe what something is built from, not which other project it's based on.** Docs, the README, device notes and the website don't name or compare other mobile Linux projects or distributions: say "Arch Linux ARM with the `linux-megi` kernel", not "based on X". Citing a properly licensed source for a fact (upstream Linux, Google's GPL kernel, postmarketOS, Mesa, Omarchy) is fine, and expected.
Expand Down
2 changes: 1 addition & 1 deletion docs/KEYBOARD-LAYOUTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -66,6 +66,6 @@ Do not edit a generated file. Every file but the two hand-made terminal ones is
3. Run `squeekboard/generate --check`. It strips the generator's additions from each file, regenerates and compares (lines 170-189, 201-211).
4. Run the tests from `packages/omamobile-shell/`: `test/all` runs `python3 -B test/keyboard-layouts.py` (every layout as squeekboard 1.43.1 parses it, the action row in every view, the globe keysym, known keysyms when libxkbcommon is installed; it exits 77, a skip, without PyYAML) and, only when that passes, `squeekboard/generate --check`; then `bash test/keyboard-languages.sh` (`omamobile-keyboard-languages` against a fake `gsettings`) (`test/all` lines 428-436, 463). Each can also be run on its own.
5. From the repository root, run `tools/pr-check` and `tests/packages` before pushing (see the tools table in `AGENTS.md`).
6. Bump `version` and note the change in the package `README.md` and this page.
6. Note the change in the package `README.md` and this page.

A new language is selectable once the package is installed with its portrait file in `squeekboard/keyboards/`: `omamobile-keyboard-languages list` then offers every top-level portrait file in the installed directory, and `omamobile-setup-user` links it at the next login. To try one before packaging, set `OMAMOBILE_KEYBOARDS_DIR` to the source directory for the list.
Loading