peerspeak/docs/release-0.6.7-prep.md

PeerSpeak 0.6.7 release prep

Prepared: 2026-08-22

Planned work day: 2026-08-23 (confirm the actual date before updating the changelog)

Release target: GitButter release page with a verified Linux x86_64 AppImage

This is a checklist, not release authorization. Pushing main, creating or pushing a tag, creating the GitButter release, and uploading assets remain explicit approval gates.

Starting checkpoint

Recheck every value live tomorrow; these are the known-good handoff values from 2026-08-22.

• PeerSpeak: main at 0823f617, 17 commits ahead of origin/main.
• PixelPass: main at ce909afc, 14 commits ahead of origin/main.
• Latest published PeerSpeak tag: v0.6.6.
• Current Cargo/Windows version: 0.6.6.
• Current field-test build: packaging/appimage/peerspeak-0.6.6-unofficial-20260822-ps0823f617-ppce909afc-fieldtest-x86_64.AppImage
• Current field-test SHA-256: f094a665dbd719929d6def32c8fd3d4943e4b88b6290e371e57b127c4e91ec45.
• The same build was staged for Lindsay at /home/lindsay/Downloads/peerspeak-0.6.6-unofficial-20260822-ps0823f617-ppce909afc-fieldtest-x86_64.AppImage.
• Preserve the existing user-owned docs/FEATURES.md modification and untracked .codex/ directory. Do not include either in release-prep commits unless the user explicitly puts them in scope.

The current one-row audio-picker build passed local AppImage artifact checks, but it still needs the final two-machine field pass. Earlier two-machine passes proved that desktop audio was heard, call voices were not echoed, and no warning was visible. They also exposed the now-fixed stale viewer/warning behavior. Do not substitute those earlier passes for testing the current build.

Version decision

The expected release is 0.6.7.

VERSIONING.md defines pre-1.0 MINOR bumps as breaking wire-protocol changes, not as a measure of feature size. The diff from v0.6.6 through 0823f617 is a large screen-share implementation and local UI/lifecycle change, but it does not change src/protocol.rs or bump an audio, friends, files, or gossip protocol version. Under the repository's policy, that makes this a PATCH release.

Use 0.7.0 only if tomorrow's final source review finds or adds an actual incompatible wire change. If that happens, identify and bump the affected Layer-2 protocol constant/domain in the same change and plan a coordinated upgrade for every peer.

Critical build-label rule

The first/home screen visibly identifies the binary as:

PeerSpeak v<package version> (<8-character commit hash>)

The same label also appears in Settings. The two pieces come from different places:

• Cargo.toml supplies the version through CARGO_PKG_VERSION and must be bumped from 0.6.6 to 0.6.7.
• build.rs runs git rev-parse --short=8 HEAD and embeds the result as PEERSPEAK_GIT_SHORT. Do not edit or bump the hash by hand.

Consequences for the release order:

1. Make and commit all source, version, changelog, and field-evidence changes.
2. Build the final AppImage from that clean final commit.
3. On first launch, verify the title screen says exactly PeerSpeak v0.6.7 (<final HEAD short hash>).
4. Verify the displayed hash equals git rev-parse --short=8 HEAD.
5. Tag that exact commit as v0.6.7.

If any commit is added after an AppImage is built—even a field-evidence or release-note commit—the embedded hash is now old. Rebuild and revalidate the AppImage. Never publish an artifact whose visible hash differs from the tag target.

Tomorrow's runbook

1. Re-establish live state

From /home/mollusk/git/butter/peerspeak:

git status --short --branch
git log -1 --oneline --decorate
git -C ../pixelpass status --short --branch
git -C ../pixelpass log -1 --oneline --decorate
git fetch --prune --tags origin
git ls-remote --heads --tags origin
df -h / /mnt/superjar
pgrep -af 'peerspeak|pixelpass|mpv|gst-launch' || true

Confirm that:

• the checkpoint commits above are still the intended source;
• neither repository has unexpected changes;
• the existing docs/FEATURES.md and .codex/ state is preserved;
• no stale call/share processes are running;
• v0.6.7 does not already exist locally, remotely, or on GitButter;
• there is enough space for one-job release builds and extracted AppImages.

2. Complete the current-build two-machine field test

Use the stamped 0823f617 AppImage on this machine and Lindsay's staged copy. Start with PeerSpeak and any old screen-share helper/player processes closed.

Run both directions, with Lindsay keeping software encode enabled where needed:

1. Mollusk hosts; Lindsay views.
2. Lindsay hosts; Mollusk views.
3. In each direction select the sole visible All system audio row.
4. Play desktop audio after the share begins, including starting a new audio stream/application during the share.
5. Talk from both machines while the desktop audio plays.
6. Stop sharing while the voice call remains active.
7. Start one more share, then have both peers leave the call.

Record all of these results explicitly:

• the picker has one desktop-audio row, not duplicate legacy/safe choices;
• desktop audio is heard by the viewer;
• neither person's call voice loops back through the shared audio;
• no transient or persistent missing-output-port warning appears;
• stopping a share clears the viewer and warning promptly;
• the viewer PixelPass child is reaped within roughly 500 ms after the remote stream ends;
• leaving the call clears the share and leaves no PeerSpeak-owned PixelPass, player, GStreamer, capture, or echo-cancellation residue.

If any row fails, stop release preparation. Save the exact visible text and relevant logs, fix the defect, run the focused regression gates, commit the fix, rebuild, and repeat the matrix.

3. Prepare the 0.6.7 source

After the current build passes:

• Change [package].version in Cargo.toml to 0.6.7.
• Refresh the root PeerSpeak package entry in Cargo.lock; inspect the diff and make sure it changes only as intended.
• Change MyAppVersion in packaging/windows/peerspeak.iss to 0.6.7, even though tomorrow's planned public asset is AppImage-only. This prevents the next Windows installer from silently retaining 0.6.6.
• Move the relevant [Unreleased] material into a dated 0.6.7 section in CHANGELOG.md and add the v0.6.7 comparison/release link.
• State that the release is wire-compatible with 0.6.6; do not claim a protocol bump.
• Summarize user-visible behavior, especially:
  • All system audio now shares desktop sound without feeding PeerSpeak's own call audio back to listeners;
  • the safe path is the single normal desktop-audio choice;
  • unsafe or incomplete audio-routing states fail closed and surface a useful warning;
  • viewer/share cleanup is prompt when a stream stops or a peer leaves;
  • the Linux AppImage bundles the matching PixelPass helper.
• Record the completed two-machine evidence in docs/screenshare-audio-exclusion-impl-plan.md.

Commit the scoped version/changelog/evidence work. Keep unrelated user changes out of the commit.

4. Run source gates on the final commit

Use the pinned Rust toolchain and one build job if disk or linker pressure is tight:

cargo fmt --all -- --check
CARGO_BUILD_JOBS=1 cargo clippy --locked --all-targets -- -D warnings
CARGO_BUILD_JOBS=1 cargo test --locked --all-targets
CARGO_BUILD_JOBS=1 cargo test --locked --doc
cargo deny --locked check
cargo audit
git diff --check
git status --short --branch

The commands mirror the repository CI, with --locked added to compilation and test gates after the intentional lockfile refresh. A gate that cannot run must be recorded as unverified; do not silently treat it as passed.

Also verify the bundled PixelPass source is still exactly the intended clean commit and run its release diagnostics before packaging:

git -C ../pixelpass status --short --branch
git -C ../pixelpass rev-parse --short=8 HEAD
cargo run --manifest-path ../pixelpass/Cargo.toml --locked -- --doctor

5. Build the final AppImage

Build from the clean, committed PeerSpeak release source and clean PixelPass source in the Ubuntu 24.04 distrobox described in packaging/appimage/README.md. Keep build caches on /mnt/superjar and use one build job if space remains tight. A representative invocation is:

distrobox enter peerspeak-appimage -- env \
  PATH="$HOME/.rustup/toolchains/1.97.1-x86_64-unknown-linux-gnu/bin:$PATH" \
  SYSTEM_DEPS_LIBSPA_INCLUDE=/run/host/usr/include/spa-0.2 \
  SYSTEM_DEPS_LIBPIPEWIRE_INCLUDE=/run/host/usr/include/pipewire-0.3:/run/host/usr/include/spa-0.2 \
  CARGO_BUILD_JOBS=1 \
  PEERSPEAK_APPIMAGE_CACHE=/mnt/superjar/peerspeak-appimage-cache \
  ./packaging/appimage/build-appimage.sh

The official output should be packaging/appimage/peerspeak-0.6.7-x86_64.AppImage. Do not overwrite the stamped 0.6.6 field-test artifact until the release is complete and verified.

6. Validate the exact final artifact

At minimum:

• record sha256sum and create a matching .sha256 sidecar;
• run --appimage-extract into an isolated scratch directory;
• inspect ldd for both bundled usr/bin/peerspeak and usr/bin/pixelpass and require no not found entries;
• inspect RUNPATH/RPATH and confirm the bundle has not captured the host's graphics, PulseAudio, or GStreamer stack contrary to the thin-AppImage policy;
• run the bundled pixelpass --capabilities and confirm desktop-audio exclusion support is advertised;
• run the bundled pixelpass --doctor with a fresh temporary GStreamer registry;
• launch the AppImage with an isolated config/data directory for a GUI smoke;
• verify the first/home screen reads PeerSpeak v0.6.7 (<final PeerSpeak HEAD short hash>);
• verify the same version/hash appears in Settings;
• confirm the bundled PixelPass binary corresponds to ce909afc (or the exact newer commit deliberately selected tomorrow).

Because the final version/evidence commit changes the embedded hash relative to the current field-test artifact, do one short two-machine confirmation using the final AppImage: connect, share All system audio, confirm desktop sound and no voice echo/warning, stop the share, and leave cleanly.

7. Publication gate

Before any external write, present the final facts to the user:

• final PeerSpeak full and short commit;
• bundled PixelPass full and short commit;
• v0.6.7 proposed tag target;
• AppImage filename, size, and SHA-256;
• title-screen version/hash observed;
• source, artifact, and two-machine gate results;
• exact release notes/assets to publish.

Then wait for explicit approval to publish.

After approval only:

1. Push main without force.
2. Confirm remote main resolves to the tested final commit.
3. Create an annotated v0.6.7 tag on that exact commit and push it.
4. Create the v0.6.7 GitButter release page from the finalized changelog text.
5. Upload peerspeak-0.6.7-x86_64.AppImage and its .sha256 sidecar.
6. Do not paste or store a GitButter token in the repository, documentation, shell history, or release artifacts.

The planned release scope is the Linux x86_64 AppImage only. Do not imply that a Windows installer, Debian package, or separate PixelPass release exists unless those artifacts are deliberately added and independently verified.

8. Verify the public release

Publication is not complete until it is independently read back:

• confirm GitButter shows the correct release title, tag, notes, and both assets;
• confirm the remote tag and remote main point to the expected commit;
• download the public AppImage to a fresh temporary path;
• verify its SHA-256 against the published sidecar and the local final hash;
• extract or run the downloaded copy and repeat the version/hash and bundled PixelPass diagnostic checks;
• save the final release URL and verification result in the implementation plan or handoff.

Failure and recovery rules

• A failed gate means no tag and no release—not a waiver.
• Never force-push or move a published tag as an automatic recovery step.
• If the tag is pushed but release creation/upload fails, stop and report the exact remote state before changing anything.
• Keep failed or candidate artifacts clearly stamped so they cannot be mistaken for the final asset.
• Remove only exact, rebuildable scratch/extraction directories when reclaiming disk space; preserve source, user changes, final artifacts, hashes, and field evidence.