Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
302 lines (197 loc) · 8.02 KB

CONTRIBUTING.md

File metadata and controls

302 lines (197 loc) · 8.02 KB

Contributing

Building

Prerequisites: Node.js and mise

# Install toolchain from mise.toml
mise install

# Install JS dependencies
npm install

# Build dev (default)
mise build

# Build release
mise build release

This builds the project with the Pebble SDK version pinned in pebble-sdk-version and provisioned by the repo scripts. The .pbw output can be found in the build directory.

Supabase (telemetry)

Telemetry uses Supabase Edge Functions + Postgres.

Install/update the CLI through mise's aqua backend (already pinned in mise.toml):

mise install
supabase --version

Create a local telemetry hash secret (TELEMETRY_HASH_SECRET):

openssl rand -hex 32

Use this value for TELEMETRY_HASH_SECRET.

Local stack and emulator testing

Start the local Supabase stack from the repo root:

supabase start

Copy .env.example to .env, then populate the telemetry keys there:

cp .env.example .env

Serve the telemetry edge function locally (from repo root):

mise telemetry-serve

For emulator validation, run:

mise install-emulator --logs

To verify inserts locally, open Supabase Studio at http://127.0.0.1:54323 and inspect public.telemetry_weather_fetch.

Hosted deployment (Supabase cloud)

Authenticate and link the repo to your Supabase project:

supabase login
supabase link --project-ref <your-project-ref>

Set function secrets in the hosted project:

supabase secrets set \
  TELEMETRY_HASH_SECRET=<paste-openssl-value>

Apply database migrations:

supabase db push --dry-run
supabase db push

Deploy the telemetry function:

supabase functions deploy telemetry-ingest

Wire release and preview builds to hosted telemetry by setting repository secret(s) used by CI workflows:

  • TELEMETRY_ENDPOINT=https://<your-project-ref>.supabase.co/functions/v1/telemetry-ingest

Optional: Supabase GitHub integration

If you use Supabase GitHub sync/branching, Supabase can auto-apply migrations and deploy functions from the supabase/ directory when branches/PRs update. Enable it in Supabase Dashboard > Project Settings > Integrations.

package.json is generated from package.template.json and profile data in profiles/.

  • Release profile: profiles/package.release.json
  • Dev profile: profiles/package.dev.json

mise build and mise build release automatically generate package.json from the template/profile before building.

If you want the extra Pebble heap debug logs, set ENABLE_MEMORY_LOGGING=1 in your .env before building or installing. This is independent of the dev/release package profile.

Release notification copy (optional “what’s new” toast on upgrade) lives in release-notifications.json, keyed by the exact version string from the template (e.g. "1.26.0"). prepare-package copies only the entry for the version being built into package.json; versions with no key ship without a notification.

If you want to regenerate package.json without building:

mise prepare-package           # dev profile (default)
mise prepare-package release   # release profile

You can run Pebble CLI commands directly, or use install tasks that build and install in one command:

# Option 1: set once in .env
cp .env.example .env
# then edit .env and set IP=<PHONE_IP>
# this installs the dev build by default
mise install-phone

# Option 2: pass IP explicitly
mise install-phone <PHONE_IP>

# Explicit release install
mise install-phone <PHONE_IP> release

# Pass through pebble install flags
mise install-phone --logs

# Legacy pass-through separator (still works)
mise install-phone -- --logs

# Install dev build via CloudPebble (default profile)
mise install-cloud

# Explicit release install via CloudPebble
mise install-cloud release

# Install dev build to emulator (defaults: profile=dev, emulator=basalt)
mise install-emulator

# Choose emulator platform
mise install-emulator aplite

# Choose emulator build type
mise install-emulator release

# Choose emulator platform and build type
mise install-emulator release aplite

# Pass through pebble install flags
mise install-emulator --logs

# Set default emulator in environment
PEBBLE_EMULATOR=aplite mise install-emulator

# Legacy pass-through separator (still works)
mise install-emulator -- --logs

# Take a screenshot from emulator (default platform: basalt)
mise screenshot-emulator

# Choose emulator platform
mise screenshot-emulator aplite

# Legacy flag form (still works)
mise screenshot-emulator -- --emulator chalk

# Set default emulator in environment
PEBBLE_EMULATOR=aplite mise screenshot-emulator

# Default output goes to screenshot/tmp/<timestamp>-<platform>.png

# Provide explicit output path / additional screenshot args
mise screenshot-emulator -- screenshot/my-capture.png --no-open --no-correction

# Take a screenshot from phone
mise screenshot-phone

# Or pass IP explicitly
mise screenshot-phone <PHONE_IP>

# Default output goes to screenshot/tmp/<timestamp>.png

# Provide explicit output path / additional screenshot args
mise screenshot-phone -- screenshot/my-capture.png

Config

You can create src/pkjs/dev-config.js to override Clay keys and local dev behavior.

Example:

module.exports.owmApiKey = 'abc123';

PKJS storage reset (dev)

Use this key in src/pkjs/dev-config.js to force a PKJS localStorage reset on each app boot while enabled:

  • clearPkjsStorageOnBoot = true

Example:

module.exports.clearPkjsStorageOnBoot = true;

Notes:

  • Keep this set to true only while testing first-install behavior.
  • Set it back to false before testing upgrade-notification behavior.
  • This is local-only dev behavior and is not written into Clay settings.

Release notification preview (dev)

Use this key in src/pkjs/dev-config.js to always show the notification for a specific version key from release-notifications.json on every app boot (ignores upgrade gating):

  • forceShowReleaseNotificationOnBoot = '1.26.0' (string must match a key in release-notifications.json exactly)

Example:

module.exports.forceShowReleaseNotificationOnBoot = '1.26.0';

Notes:

  • Useful when package.json is still on an older version but you want to iterate on copy for the next release entry.
  • Remove the key (or comment it out) when testing normal upgrade behavior.
  • This is local-only dev behavior and is not written into Clay settings.

Mock weather (emulator/dev)

Use these keys in src/pkjs/dev-config.js:

  • provider = 'mock' enables the mock provider.
  • mockCity sets the city label independently.
  • mockScenario selects the active built-in scenario.

Scenario data is tracked in git inside src/pkjs/weather/mock.js (MOCK_SCENARIOS).

Minimal shape:

module.exports.provider = 'mock';
module.exports.mockCity = 'New York, NY';
module.exports.mockScenario = 'clearMorning';

Notes:

  • If mockScenario is missing/invalid, the app falls back to the first built-in scenario.
  • To add/edit scenarios, update MOCK_SCENARIOS in src/pkjs/weather/mock.js.
  • startEpoch and sunEvents[].epoch should be coherent in emulator local time (the graph and shading use watch localtime).

Emulator time overrides (applied automatically)

scripts/install-emulator.sh reads these keys from dev-config.js after install:

  • emuTimeFormat: 12h or 24h
  • emuTime: HH:MM:SS or Unix seconds (e.g. 1772870400)

Then run:

mise install-emulator --logs

Reset behavior when keys are removed:

  • emuTimeFormat defaults to 24h
  • emuTime fallback order is:
    1. explicit emuTime in dev-config.js
    2. emuTime of active mock scenario (when provider = 'mock', if present)
    3. startEpoch of active mock scenario (when provider = 'mock')
    4. current host time

Upgrading pebble-tool

This project pins pipx:pebble-tool to an exact version in mise.toml (fully resolved in mise.lock).

To bump the pinned version:

mise upgrade "pipx:pebble-tool" --bump
mise install