Skip to content

Upgrading

Extension version

Content is stored by the extension, not by the page, so an upgrade keeps it. The IndexedDB database is named guidepost at version 1; its schema has not changed since the first release. An install made before the product rename holds its content under the earlier database name. On first start after the rename, the extension copies that database into guidepost in one transaction and leaves the original in place, so nothing is lost and a downgrade still finds its data. The copy runs once: it is skipped when guidepost already exists. Bundles exported before the rename import unchanged (decision 89).

Flavour How an upgrade arrives
Store The browser updates it from the store
Managed, force-installed from a self-hosted CRX Raise version in the update manifest at your update_url; the browser polls it
Unpacked Rebuild, then press Reload on the extensions page

The service worker re-registers the content script for the origins the extension holds on install, on browser startup, and whenever permissions are added or removed.

Content schema version

SCHEMA_VERSION is currently 2. The migrateItem function upgrades older items when they are read, so imported bundles and stored content from schema 1 load on a current build. The 1 to 2 migration adds tags and a default locale (en-CA).

Rules for reviewers:

  • Migrations run on read and do not rewrite stored data until the item is saved again.
  • A change that adds a required field needs a migration and a SCHEMA_VERSION bump.
  • Regenerate the JSON schemas with pnpm schema:export and commit them; this site's content schema reference is built from them.

Release procedure

The release steps in docs/RUNBOOK.md are a placeholder until a store listing and signing key exist. Do not treat this page as the procedure.

Gotchas

  • The manifest key must stay the same for the unpacked and self-hosted id to stay stable. Do not remove it from a build that devices already run.
  • A managed upgrade that changes GUIDEPOST_APPROVED_ORIGINS changes the permission set. Browsers may disable an extension until an administrator or user accepts new permissions, depending on policy.
  • A service worker restart (the browser stops it after about 30 seconds idle) is normal; state that must survive is in storage.session or IndexedDB.