lfg2025/archy
1
0
Fork 0
Code Issues 11 Pull Requests Actions Packages Projects Releases 7 Wiki Activity
Files
main
archy/docs/1.8.12-RELEASE-PLAN.md
T

13 KiB
Raw Permalink Blame History

Archipelago 1.8.12-alpha Release Plan

Target date: 2026-09-11 Scope: OTA, signed app registry, canonical Nostr source publication, Companion 0.5.32 alpha, and an x86_64 installer ISO Candidate base: f5c0ba85 plus the release-preparation changes documented here

Release Outcome

This release is complete only when all of the following are true:

  1. Existing nodes can install the signed OTA and retain AIUI, app data, app manifests, Nostr identities, Lightning state, and network configuration.
  2. A fresh ISO installation boots, reports 1.8.12-alpha, and serves the same dashboard/runtime payload as the OTA.
  3. The signed app registry contains GitWorkshop, its embedded manifest, and the registry-owned Source promotion.
  4. Archipelago's canonical repository is announced by npub1w3sqdkrhn0gyuvsex32effzgnfpyde6qrrc4u467flg5e9txh4wsfn5vjg as the stable identifier archy, is cloneable through nostr://, and opens in GitWorkshop from the Source promotion.
  5. Contributors can create an issue or proposal without gaining canonical merge, release-tag, catalog-signing, or OTA-signing authority.

Shipping GitWorkshop alone does not satisfy item 4. The client is the interface; the signed NIP-34 announcement and reachable Git object servers are the source publication.

Audited Candidate State

Ready

  • The accumulated candidate is committed and the development node is healthy.
  • GitWorkshop is healthy behind the authenticated same-origin app gate.
  • The app works as a top-level Companion WebView and as a browser tab; the node signer remains consent-gated and identity-switchable.
  • The Source icon, description, banner, Popular/All Apps placement, and maintainer npub are present in the development catalog.
  • Payment receipts, Minibits claim persistence, update cancellation, app credential interstitials, Gitea limits, certificate guidance, and the pasta listener repair are included in the candidate.
  • ngit 2.6.3 and git-remote-nostr 2.6.3 are installed on the node.
  • The existing public Gitea source and Smart HTTP clone endpoints respond with HTTP 200.
  • The release-root signer exists locally as a binary, while its mnemonic remains correctly offline.
  • ISO dependencies (xorriso, mksquashfs, and QEMU) are installed.
  • The corrected release gate passed on 2026-09-11: 1,093 frontend tests, production UI build, registry candidate/trust checks, Rust check, 114 focused backend tests plus orchestration, and live dashboard/AIUI/RPC probes. Android lint and the mobile Chromium signer-handoff regression also pass.
  • GitWorkshop's refreshed dependency lock reports zero production or development npm advisories. Its type-check, all 152 unit tests, and exact Archipelago subpath production build pass with fflate 0.8.3, React Router 7.18.3, and Vitest 5.0.0.
  • The locally served Companion candidate is 28,157,847 bytes with SHA-256 30e0b6257f17bb5e072941ccce6fde04b6c8ae59a49b45169e1920aec1b108cf.
  • The Discover banner and automatic Companion prompt read that artifact's no-cache metadata, display 0.5.32 build 52, and remember dismissal per build; the ISO gate derives the same expected version from the Android project.
  • The owner accepted the risk of redistributing the pinned, unlicensed GitWorkshop revision on 2026-09-11. NOTICE and UPSTREAM.md disclose that decision without claiming an upstream license.

Not Yet Complete

  • This checkout is not logged into ngit and has no Nostr repository remote or cached kind 30617 announcement.
  • The production signed catalog still contains 61 apps but not archipelago-source or storefront; a freshly generated candidate contains 62 apps, 61 embedded manifests, GitWorkshop 0.4.0, and the Source promotion.
  • The previous public Companion download was 0.5.28-debug. A 0.5.32-debug candidate has now been built with the same certificate and can update that alpha channel; the accepted 0.5.32-uat build remains a separate package.
  • The shared debug certificate is intentionally public and its private key is reachable in an existing public Git branch. It provides upgrade continuity, not production authenticity. A future production Companion must use the com.archipelago.app package with a privately held release key.
  • The repository is large: this checkout has about 5.4 GiB of packed objects, and the Gitea repository is about 5 GiB. Public GRASP replication must be allowed enough time and verified rather than assumed complete.
  • The provided secrets audit reports known false positives in documentation, path-variable names, and deliberate test keys. Before Nostr publication, record that review and ensure local Git remote credentials are rotated; local .git/config credentials are not tracked and must never be copied into an announcement or release log.

Required Owner Inputs

These secrets must be entered interactively and must not be sent in chat, committed, placed in shell history, or stored on the node:

  1. Access to the Nostr maintainer identity matching the npub above. Prefer an interactive NIP-46 connection through ngit account connect; do not pass an nsec on a command line.
  2. The 24-word Archipelago release-master mnemonic for three signing actions: the OTA manifest, the app catalog, and the ISO checksum document.
  3. A decision to publish 0.5.32 on the existing explicitly non-production .debug Companion channel, omit it, or pause for a secure production-app signing ceremony.

The shared Companion update certificate is not a production secret. It was temporarily recovered from the public branch, verified against the distributed 0.5.28 APK, used to build the 0.5.32 alpha upgrade candidate, and removed from the working tree. Neither it nor the UAT keystore belongs in the release commit.

Execution Order

Gate A — Freeze And Production Companion

  1. Verify the shared Companion certificate against the existing public APK before building anything. This is complete for the alpha candidate.
  2. Build the 0.5.32 shared-key alpha APK with v1, v2, and v3 signature schemes.
  3. Verify package ID, version code/name, signing digest, and install-as-upgrade behavior on the owner's phone.
  4. Stage the APK and its JSON version metadata in the dashboard payload.
  5. Run formatting, frontend type checking/unit tests/build, Android lint/build, focused backend tests, manifest validation, registry-candidate validation, secret review, and live node smoke probes.
  6. Deploy that exact build on this node and perform the short final UAT: GitWorkshop and IndeedHub first login, identity switching, Companion WebView, external tab, certificate install, payment receipt, update cancellation, and credential interstitial.

Stop on any failure. Do not sign or publish a workaround build.

Gate B — Publish Archipelago Source Through Nostr

Run Nostr publication from a disposable clean clone so ngit init cannot repoint or rewrite the release checkout's remotes.

  1. Confirm the clean clone matches the final candidate and contains LICENSE, CONTRIBUTING.md, SECURITY.md, and NOTICE.
  2. Connect ngit interactively to the canonical maintainer identity and verify ngit account whoami reports the expected npub.
  3. Publish identifier archy, title Archipelago, the public project description/homepage, the existing Gitea HTTPS clone URL, and multiple current public GRASP services. Use at least relay.ngit.dev and gitnostr.com; add an Archipelago-operated GRASP service later without changing the repository coordinate.
  4. Allow the complete repository push to finish. Do not treat a published announcement as proof that all Git objects arrived.
  5. Verify the announcement author, identifier, relays, clone URLs, default branch, and release tags with ngit repo.
  6. In a second empty directory, clone the printed nostr:// URL and compare its HEAD tree to the candidate.
  7. Open /npub1w3sqdkrhn0gyuvsex32effzgnfpyde6qrrc4u467flg5e9txh4wsfn5vjg/archy in the packaged GitWorkshop and confirm README/code browsing works.
  8. Publish a test issue/proposal from a non-maintainer identity, review it from the maintainer identity, and confirm it cannot change canonical refs without maintainer authorization.
  9. Confirm clone/browse still work with one GRASP server unavailable. A later infrastructure release must add an Archipelago-operated GRASP endpoint; the signed coordinate remains stable when servers change.

The Source promotion carries the deterministic npub/identifier deep-link. It must not be published to the registry until steps 5–8 pass.

Gate C — Prepare And Publish OTA 1.8.12-alpha

  1. Convert the top Unreleased changelog section into v1.8.12-alpha (2026-09-11) and synchronize What's New.
  2. Run bash scripts/create-release.sh 1.8.12-alpha. Enter the release mnemonic once when prompted and terminate input with Ctrl-D.
  3. Verify the new release commit, annotated tag, staged backend/frontend artifacts, signed pending manifest, embedded AIUI, APK version, and clean tree.
  4. Publish with SKIP_ISO=1 scripts/publish-release-assets.sh 1.8.12-alpha gitea-vps2. The script uploads and hashes artifacts before pushing the fleet-visible manifest. Never push main manually around this ordering.
  5. Verify both local and public manifests, both asset hashes, public HTTPS download links, and update availability from this node.
  6. Apply the OTA to this node first, reboot if requested, and rerun live smoke probes before allowing the catalog publication.

Gate D — Publish The Signed App Registry

This follows the OTA canary because GitWorkshop's manifest builds from /opt/archipelago/docker/archipelago-source, which older nodes do not have.

  1. Generate releases/app-catalog.json from the final manifests.
  2. Require 62 entries, 61 embedded manifests, archipelago-source 0.4.0, registry-owned storefront metadata, and the canonical Source deep-link.
  3. Run strict metadata, manifest, and deployed-registry trust-floor checks.
  4. Sign the exact catalog bytes using bash scripts/sign-catalog.sh and verify the pinned release-root DID.
  5. Commit and push only the signed catalog after the OTA canary succeeds.
  6. Confirm /api/app-catalog verifies the signature and a fresh node can see, install, launch, stop, start, and uninstall GitWorkshop.

Gate E — Build, Test, Sign, And Attach The ISO

  1. From clean main with the live signed 1.8.12 manifest and tag, run bash scripts/build-iso-release.sh. Do not use --skip-gates or --no-qemu for the publishable candidate.
  2. Require the release harness, strict catalog check, full Rust test suite, version/artifact checks, ISO mount smoke test, and QEMU boot attempt.
  3. Record the ISO filename, byte size, SHA-256, build commit, and whether QEMU was conclusive. If QEMU is inconclusive, boot the ISO on the target test machine before publication.
  4. Sign the checksum document with bash scripts/sign-iso-checksums.sh <iso> and cryptographically verify it.
  5. Attach the ISO, plain checksum, and signed checksum JSON by rerunning scripts/publish-release-assets.sh 1.8.12-alpha gitea-vps2.
  6. Verify Gitea's stored sizes and public HTTPS links, then download/hash the public checksum documents. Flash/boot/install on real hardware before calling the ISO generally available.

Rollback Rules

  • OTA: the live manifest remains 1.8.11-alpha until all 1.8.12 artifacts have uploaded and verified. If canary application fails, do not publish the new catalog; restore the previous manifest/artifacts through the established rollback path.
  • Registry: retain the previously signed catalog. Roll back by publishing a newly signed catalog that removes GitWorkshop or restores its prior entry; never edit signed JSON in place.
  • Nostr source: repository state is authoritative only when signed by the configured maintainer. Add replacement servers before removing failed ones, then republish and run ngit sync.
  • ISO: an ISO is not referenced by the OTA manifest. A failed ISO build/upload cannot block or corrupt an already verified OTA; do not advertise a partial attachment.
  • Companion: retain 0.5.28 and the verified alpha signer until 0.5.32 installs as an upgrade. Never replace the public APK with the differently signed UAT build. Do not describe the public debug-key channel as production-secure.

Final Release Record

Before announcing completion, record in the release notes:

  • release/tag/commit and signed manifest DID;
  • backend and frontend SHA-256 values;
  • signed catalog commit, app count, and verification result;
  • canonical nostr:// URL, NIP-34 coordinate, GRASP/clone endpoints, and clone verification commit;
  • Companion package/version/signing digest and APK SHA-256;
  • ISO filename/size/SHA-256/signature and smoke/QEMU/real-hardware results;
  • owner UAT acceptance and the explicit GitWorkshop no-license/dependency-risk decisions.
Reference in New Issue View Git Blame Copy Permalink