OpenPhone

Release Process

This document defines the public release process for OpenPhone-owned project releases.

Versioning

OpenPhone uses semantic versioning for public project releases:

MAJOR.MINOR.PATCH

Before 1.0.0, releases are developer previews. Compatibility is not guaranteed, and device images may require a clean wipe.

The first public target is:

0.0.1

Release Types

Source Release

A source release includes:

  • Git tag.
  • GitHub release notes.
  • Source archive generated by GitHub.
  • Changelog entry.
  • Known issues.

Device Preview Release

A device preview release may additionally include:

  • OTA ZIP.
  • SHA-256 checksum.
  • Supported device/codename.
  • Required base firmware or security patch level.
  • Flashing and wipe instructions.
  • Validation checklist and result summary.

Source Of Truth

Each release has three tracked public records:

  • docs/releases/CHANGELOG.md for the cumulative project history.
  • A versioned release-notes file under docs/releases/, such as docs/releases/0.0.1.md, for the human-readable release page body.
  • The GitHub Release at https://github.com/secondly-com/OpenPhone/releases, which is the public distribution page for source archives, OTA artifacts, SHA256SUMS, and ARTIFACTS.md.

Release evidence that contains private device details, screenshots, trajectories, audit exports, local paths, tokens, or signing material must stay out of tracked docs. Use ignored .worktree/ paths or private GitHub Actions artifacts for raw evidence, then summarize safe conclusions in release notes.

v0.0.1 Checklist

Repository:

  • README.md explains the project state honestly.
  • docs/README.md is the documentation index.
  • docs/BUILD.md explains Linux build requirements.
  • docs/TESTING.md explains repo, device, and eval validation.
  • docs/devices/MATRIX.md and docs/devices/tegu.md describe Pixel 9a status.
  • docs/releases/CHANGELOG.md has a 0.0.1 section.
  • LICENSE and the files under docs/legal/ are present.

Validation:

  • ./scripts/check.sh passes.
  • git diff --check passes.
  • ./scripts/verify-tegu-device.sh output is captured for any Pixel 9a OTA artifact that is being published.
  • No API keys, private SSH keys, device secrets, or generated build artifacts are committed.

Device artifact, when published:

  • OTA ZIP is produced on a Linux Android build host.
  • OTA SHA-256 is recorded.
  • Private release-signing keys are prepared outside the repository with scripts/prepare-release-signing.sh.
  • Release target-files and OTA signing is run with scripts/sign-release-ota.sh in the private build environment.
  • scripts/generate-release-manifest.sh <version> <artifact-dir> has produced SHA256SUMS and ARTIFACTS.md for the release artifact directory.
  • scripts/generate-ota-feed.sh has produced an updater feed JSON when the release is intended for OTA discovery.
  • scripts/validate-ota-feed.sh passes against the feed and staged artifact directory.
  • scripts/validate-release-artifacts.sh <artifact-dir> passes against the staged release directory.
  • scripts/validate-trajectory-export.sh <trajectory.zip> passes for every assistant trajectory export used as release validation evidence.
  • scripts/validate-audit-evidence-export.sh <audit.json> passes for every framework audit export used as release validation evidence.
  • Pixel 9a boot and service checks are recorded.
  • Assistant package diagnostics are recorded, including package version and privileged component declarations.
  • Accessibility/UI-tree builds record whether OpenPhoneAccessibilityService is visible to PackageManager and enabled in secure settings.
  • Known wipe/upgrade behavior is documented.
  • Any ADB authorization/onboarding caveats after a clean data wipe are documented in the release notes.

Release Signing Preparation

Create a private signing workspace outside the repository:

scripts/prepare-release-signing.sh \
  --keys-dir "$HOME/.openphone/signing/openphone-release"

If a synced Android tree is available, pass it to print the exact development/tools/make_key commands:

scripts/prepare-release-signing.sh \
  --keys-dir "$HOME/.openphone/signing/openphone-release" \
  --android-dir .worktree/android

The helper creates a private key-map.txt, README, and .gitignore. It does not put private keys inside the repository. Use the generated key map with Android releasetools (sign_target_files_apks and ota_from_target_files) in the private build environment.

Sign a target-files archive and generate a signed OTA:

scripts/sign-release-ota.sh \
  --android-dir .worktree/android \
  --keys-dir "$HOME/.openphone/signing/openphone-release" \
  --target-files .worktree/android/out/target/product/tegu/obj/PACKAGING/target_files_intermediates/openphone_tegu-target_files.zip \
  --output-dir .worktree/releases/signed \
  --name openphone_tegu-v0.0.1

Use --dry-run first to inspect the exact releasetools commands. The signing script refuses to use a key directory inside the OpenPhone repository.

GitHub Release Notes Template

Stage only the files intended for publication into a clean release directory, then generate the artifact manifest before drafting release notes:

mkdir -p .worktree/releases/v0.0.1-preview
cp .worktree/artifacts/tegu/openphone_tegu-<build>-ota.zip \
  .worktree/releases/v0.0.1-preview/
scripts/generate-release-manifest.sh 0.0.1-preview .worktree/releases/v0.0.1-preview
scripts/validate-release-artifacts.sh .worktree/releases/v0.0.1-preview
scripts/prepare-github-release.sh \
  0.0.1-preview .worktree/releases/v0.0.1-preview docs/releases/0.0.1.md

Attach the generated OTA ZIP, SHA256SUMS, and ARTIFACTS.md to the GitHub release when publishing device preview artifacts. The preparation script writes gh-release-draft.sh, which can be inspected before creating the draft with GitHub CLI.

Generate an updater feed for a staged OTA:

scripts/generate-ota-feed.sh \
  --version 0.0.1-preview \
  --channel preview \
  --device tegu \
  --artifact .worktree/releases/v0.0.1-preview/openphone_tegu-<build>-ota.zip \
  --base-url https://downloads.example/openphone/v0.0.1-preview \
  --release-notes-url https://github.com/secondly-com/OpenPhone/releases/tag/v0.0.1-preview \
  --output .worktree/releases/v0.0.1-preview/ota-feed-tegu-preview.json \
  --requires-wipe

scripts/validate-ota-feed.sh \
  .worktree/releases/v0.0.1-preview/ota-feed-tegu-preview.json \
  .worktree/releases/v0.0.1-preview

The feed contract is documented in schemas/ota-feed.schema.json. The assistant now includes the first preview on-device OTA client for this feed: it checks that the feed targets the current device, downloads the chosen OTA ZIP to Downloads/OpenPhone, and verifies size and SHA-256 before making the file visible. Installation is still manual for 0.0.1; use recovery sideload or the documented host flashing flow.

GitHub Actions Release Workflow

Use .github/workflows/release.yml for the normal device-preview path. The workflow requires:

  • version, such as v0.0.1-preview.1;
  • device, currently tegu;
  • release_notes, the markdown file that becomes the GitHub Release body;
  • prerelease, usually true before 1.0.0;
  • make_latest, usually false for preview builds unless this release should become the repository's Latest release.

The workflow validates the repository, confirms the release-notes file exists, builds the OTA on the openphone-build runner, stages the OTA, generates SHA256SUMS and ARTIFACTS.md, validates the staged directory, and publishes the GitHub Release with those assets.

Before dispatching a release:

  • move relevant entries from [Unreleased] in docs/releases/CHANGELOG.md into the target version section;
  • update the target docs/releases/<version>.md notes;
  • run or review the relevant device/eval evidence;
  • decide whether the release should become GitHub's Latest release.
## OpenPhone 0.0.1

Developer preview for OpenPhone.

### Supported Devices

- Google Pixel 9a (`tegu`) - development target

### Highlights

- Privileged OpenPhone Assistant app.
- OS-level OpenPhone agent manager service.
- Task, screen, action, policy, confirmation, and audit plumbing.
- Assistant-owned cursor/status overlay.
- Development screenshot, UI-tree, trajectory, and model-adapter paths.

### Artifacts

- Source archive
- OTA ZIP: TBD
- SHA-256: TBD

### Known Issues

- Not a consumer-ready ROM.
- Device support is limited.
- Full autonomous agent loop is still in progress.
- Production signing is not yet used for the preview artifact, but private
  signing workspace preparation is documented.
- On-device OTA updater is not implemented; the first server-side OTA feed
  contract and generator exist.
- Hardware validation is incomplete.
- A clean wipe may require completing onboarding and re-authorizing USB
  debugging before ADB shell/logcat/install channels work.

### Flashing Notes

See `docs/BUILD.md`, `docs/TEGU_BOOTCHAIN.md`, and `docs/devices/tegu.md`.

Pixel 9a Boot Chain Notes

Previous Page

Releases

Next Page

On this page

VersioningRelease TypesSource ReleaseDevice Preview ReleaseSource Of Truthv0.0.1 ChecklistRelease Signing PreparationGitHub Release Notes TemplateGitHub Actions Release Workflow