diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 5f4b7af..0b06829 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -121,6 +121,29 @@ By contributing, you represent and warrant that: rate limits, data minimization, or licensing controls without explicit approval. +## CI Ladder + +CI runs in three tiers. Only the first tier runs automatically on fork PRs; +the heavier tiers need maintainer involvement. + +1. **Automatic on every PR** (`ci.yml`, ~10 minutes): docs-site build, + `./scripts/check.sh` (required files, JSON validity, schema + cross-consistency, runtime protocol validation, broker smoke test, Node + contract tests, assistant Java compile check), and `git diff --check`. + Run `./scripts/check.sh` locally before pushing — it is the same check. +2. **Maintainer-triggered** (`gcp-lab.yml`): a maintainer applies the + `run-gcp-lab` label to run the GCP emulator smoke lab (~30–60 minutes). + Ask for a lab run in a PR comment when your change affects the image, + overlay, patches, or on-device behavior. +3. **Release and nightly only**: `emulator.yml` (self-hosted arm64 emulator + smoke) and `eval.yml` (nightly on-device trajectory smokes and benchmark). + These do not run on fork PRs. + +Reviews are best-effort. If tier 1 is green and you need a lab run or a +review, comment on the PR. + +The milestone tracks and current priorities are in [ROADMAP.md](../ROADMAP.md). + ## Questions For licensing, commercial use, or contribution questions, contact support@secondly.com. diff --git a/README.md b/README.md index 11c7200..969c03d 100644 --- a/README.md +++ b/README.md @@ -172,6 +172,12 @@ See [docs/devices/MATRIX.md](docs/devices/MATRIX.md) and Contributions, issues, and device validation reports are welcome under the terms in [.github/CONTRIBUTING.md](.github/CONTRIBUTING.md). +- [ROADMAP.md](ROADMAP.md) — milestone tracks and current priorities. +- [Discussions](https://github.com/secondly-com/OpenPhone/discussions) — for + questions, ideas, and show-and-tell; use issues for bugs and concrete work. +- [No-build contribution path](docs/contributing/no-build.md) — schemas, + broker, integrations, protocol, and docs work needs no Android build host. + ## Star History [![Star History Chart](https://api.star-history.com/svg?repos=secondly-com/OpenPhone&type=Date)](https://www.star-history.com/#secondly-com/OpenPhone&Date) diff --git a/ROADMAP.md b/ROADMAP.md new file mode 100644 index 0000000..a643f31 --- /dev/null +++ b/ROADMAP.md @@ -0,0 +1,45 @@ +# OpenPhone Roadmap + +Work is organized into five milestone tracks. Each links to a GitHub +milestone with the full issue list. If you want to contribute, pick an issue +from a track that matches your interests — `good first issue` labels mark +entry-level work, and the [no-build contribution +path](docs/contributing/no-build.md) covers what you can do without an +Android build host. + +Tracking issue: [#97](https://github.com/secondly-com/OpenPhone/issues/97). + +## [M1: Safety & Policy Hardening](https://github.com/secondly-com/OpenPhone/milestone/1) + +Fix policy-bypass and confirmation gaps across the assistant, watchers, and +the ADB/MCP surface. In progress — capability inference now fails closed and +the external ADB/MCP transport refuses state-changing tools by default. +Must land before wider distribution. + +## [M2: Testability & Decomposition](https://github.com/secondly-com/OpenPhone/milestone/2) + +Break up the assistant god classes, add a JUnit harness, and cover +pure-logic classes with tests. Started — thread-safety fixes are under +review; decomposition has not begun. + +## [M3: Upstream Durability](https://github.com/secondly-com/OpenPhone/milestone/3) + +Fork `frameworks_base`, add patch-apply canary CI against LineageOS +upstream, and write a LineageOS-bump runbook so upstream bumps stop being +high-risk events. Not started; post-0.1. + +## [M4: Provider & Runtime Maturity](https://github.com/secondly-com/OpenPhone/milestone/4) + +Broker streaming, rate limiting, and provider dispatch; MCP spec +compliance; runtime protocol versioning; a shared runtime-protocol package. +In progress — MCP stdio framing and broker rate-limiter fixes have landed. + +## [M5: Contributor Experience & Community](https://github.com/secondly-com/OpenPhone/milestone/5) + +Prebuilt emulator images, a documented no-build contribution path, and +community infrastructure (Discussions, roadmap, contribution docs). In +progress. + +--- + +Updated quarterly. Horizons are directional, not commitments. diff --git a/docs/BUILD.md b/docs/BUILD.md index 4cbaf69..a520ce3 100644 --- a/docs/BUILD.md +++ b/docs/BUILD.md @@ -3,6 +3,12 @@ OpenPhone uses Android's normal `repo` workflow. This repository stays small and contains only OpenPhone-owned code, manifests, scripts, and patches. +> **Minimum build-host specs: 64 GB RAM, ~700 GB fast disk, x86_64 Linux.** +> A full Android build will not complete on a typical laptop. If your machine +> does not meet the bar, you can still contribute meaningfully without an +> Android build host — see the +> [no-build contribution path](contributing/no-build.md). + ## Prerequisites - Linux Android build host dependencies installed for full device images. diff --git a/docs/contributing/meta.json b/docs/contributing/meta.json new file mode 100644 index 0000000..f720f3e --- /dev/null +++ b/docs/contributing/meta.json @@ -0,0 +1,6 @@ +{ + "title": "Contributing", + "pages": [ + "no-build" + ] +} diff --git a/docs/contributing/no-build.md b/docs/contributing/no-build.md new file mode 100644 index 0000000..112aac4 --- /dev/null +++ b/docs/contributing/no-build.md @@ -0,0 +1,92 @@ +# Contributing Without an Android Build Host + +A full OpenPhone Android build needs 64 GB RAM, ~700 GB fast disk, and an +x86_64 Linux host. Most of the repository does not. Everything below is +plain JSON, JavaScript, Python, shell, and markdown, validated end-to-end by +`./scripts/check.sh` on an ordinary laptop. + +## What you can work on + +- [`schemas/`](https://github.com/secondly-com/OpenPhone/tree/main/schemas) + — JSON Schema contracts for action requests, tools, screen context, audit + events, trajectories, OTA feeds, and eval reports. `check.sh` loads + several of them for cross-consistency checks. +- [`runtime/protocol/`](https://github.com/secondly-com/OpenPhone/tree/main/runtime/protocol) + — the Runtime Agent Protocol manifests (commands, events, capabilities) + and their validator. +- [`integrations/cli`](https://github.com/secondly-com/OpenPhone/tree/main/integrations/cli), + [`integrations/mcp-server`](https://github.com/secondly-com/OpenPhone/tree/main/integrations/mcp-server), + [`integrations/adb`](https://github.com/secondly-com/OpenPhone/tree/main/integrations/adb) + — Node CLI, MCP server, and ADB transport. Pure `.mjs`, no build step. +- [`services/model-broker/`](https://github.com/secondly-com/OpenPhone/tree/main/services/model-broker) + — the dependency-free Python model broker and its deploy files. +- [`tests/integrations/`](https://github.com/secondly-com/OpenPhone/tree/main/tests/integrations) + — Node contract tests for the CLI, MCP server, and OpenClaw plugin policy + buckets. +- `docs/` — everything on the docs site. +- [`scripts/`](https://github.com/secondly-com/OpenPhone/tree/main/scripts) + — sync, validation, and release helpers. + +## Setup + +```bash +git clone https://github.com/secondly-com/OpenPhone.git +cd OpenPhone +node --version # CI uses Node 24 +python3 --version # any recent Python 3 +./scripts/check.sh +git diff --check +``` + +`check.sh` skips the standalone Java compile check when no Android SDK is +present (or set `OPENPHONE_SKIP_JAVA_CHECK=1`). Everything else — required +files, JSON validity, schema cross-consistency, protocol validation, broker +smoke test, and the Node contract tests — runs locally in a few minutes. + +To build the docs site locally, run `./scripts/build-docs.sh` (needs `npm`). + +## Example tasks + +### Add a schema field + +Contracts live in `schemas/*.schema.json`. To document a new payload field, +edit the schema (for example a new optional property in +`screen-context.schema.json`), keep `required` accurate, and run +`./scripts/check.sh`. Note which schemas drive validator behavior directly — +read +[schemas/README.md](https://github.com/secondly-com/OpenPhone/blob/main/schemas/README.md) +before changing enums, `required` keys, or `const` markers. + +### Add or change a runtime command + +Runtime commands are declared in +`runtime/protocol/openphone-commands.json`. Each entry needs a name, +`android_tool`, capability, risk, exposure, and input/output schemas. +`runtime/protocol/validate-runtime-protocol.mjs` (run by `check.sh`) +cross-checks the manifest against the Android action registry, the OpenClaw +plugin command buckets, and the Android adapter mapping — so a new command +also touches those files, but all of them are text edits validated without +a build. Start by reading an existing entry like `openphone.apps.search`. + +### Fix or improve docs + +Edit the markdown under `docs/`, keep relative links valid, and run +`./scripts/check.sh` plus `./scripts/build-docs.sh` if you can. New pages +need an entry in the directory's `meta.json` to appear in the docs-site nav. + +### Extend a broker or integration test + +The broker's behavior contract is exercised by +`scripts/smoke-test-model-broker.sh` (started against a fake provider, no +API key needed). The Node surfaces are covered by +`tests/integrations/*.mjs`, which run the CLI and MCP server in dry-run mode +with no device attached. Adding an assertion for an uncovered behavior is a +small, high-value PR. + +## Before opening a PR + +Read the contributor terms in +[.github/CONTRIBUTING.md](https://github.com/secondly-com/OpenPhone/blob/main/.github/CONTRIBUTING.md), +keep the PR focused, and make sure `./scripts/check.sh` and +`git diff --check` pass. The CI ladder that runs on fork PRs is documented +there too. diff --git a/docs/meta.json b/docs/meta.json index 698013f..ee827d3 100644 --- a/docs/meta.json +++ b/docs/meta.json @@ -19,6 +19,7 @@ "GMS", "---Contribute---", "contribution-guide", + "contributing", "AI_FIRST_ENGINEERING", "TESTING", "RELEASE_PROCESS", diff --git a/docs/quickstart.md b/docs/quickstart.md index b6ba706..3ef2d55 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -8,6 +8,12 @@ If you just want to read about the system, jump to [Architecture](/docs/ARCHITECTURE). If you want to flash an actual Pixel 9a, see [Build](/docs/BUILD). +> **Minimum build-host specs: 64 GB RAM, ~700 GB fast disk, x86_64 Linux.** +> The build host is the machine that produces the image, not the one that +> runs the emulator. If no machine you have meets the bar, see the +> [no-build contribution path](/docs/contributing/no-build) — schemas, +> broker, integrations, protocol, and docs work needs no Android build. + ## What you get After this quickstart you will have: