From 7544a9a7152dd83c2d13fdaea08ea82834e5faa4 Mon Sep 17 00:00:00 2001
From: D1a0y1bb <1962389612@qq.com>
Date: Wed, 13 May 2026 12:06:15 +0800
Subject: [PATCH] docs: add v0.2.0-beta release notes

---
 PitcherPlantApp/ReleaseNotes/v0.2.0-beta.md | 120 ++++++++++++++++++++
 1 file changed, 120 insertions(+)
 create mode 100644 PitcherPlantApp/ReleaseNotes/v0.2.0-beta.md

diff --git a/PitcherPlantApp/ReleaseNotes/v0.2.0-beta.md b/PitcherPlantApp/ReleaseNotes/v0.2.0-beta.md
new file mode 100644
index 0000000..1dc422e
--- /dev/null
+++ b/PitcherPlantApp/ReleaseNotes/v0.2.0-beta.md
@@ -0,0 +1,120 @@
+### Build
+
+PitcherPlant v0.2.0-beta is a beta-channel release focused on audit hardening, report review performance, native macOS polish, and release workflow reliability.
+
+- Version: 0.2.0-beta
+- Release tag: v0.2.0-beta
+- Channel: beta / RC channel through `appcast-beta`
+- Update feed: `https://github.com/D1a0y1bb/PitcherPlant/releases/download/appcast-beta/appcast.xml`
+- GitHub Release behavior: published as a pre-release and not promoted to GitHub Latest
+- Distribution target: ad-hoc signed GitHub beta artifacts when Developer ID secrets are not available
+- Notarization: not notarized in the current ad-hoc beta distribution path
+
+### User-Facing Changes
+
+#### Workspace and Navigation
+
+- Adds and refines the workspace route map entry so reviewers can scan workspace flow and navigation context from the main window.
+- Polishes the workspace dashboard status cards for clearer audit state, report state, and review progress scanning.
+- Refines the native main toolbar and sidebar styling while keeping the app on the standard macOS window and source-list structure.
+- Simplifies the workspace map entry after review so the navigation surface stays focused on actionable workspace state.
+
+#### Settings
+
+- Redesigns the Settings window toward a more native macOS preferences layout.
+- Improves settings row spacing, field alignment, path controls, and visual hierarchy.
+- Expands localization coverage for settings, workspace, reports, updates, and validation messages.
+- Keeps settings presentation consistent with the main app shell instead of reintroducing older custom window chrome patterns.
+
+#### Reports and Inspector
+
+- Report Inspector image previews now decode asynchronously through a thumbnail cache.
+- Large code snippets and diffs are rendered through actor-backed caches so switching report rows is less likely to block the UI.
+- Report row rendering is tied to the selected row identity to avoid showing stale attachments while cached work is still resolving.
+- Cross-batch evidence selection now uses the real composite row ID, which keeps table selection aligned with the visible evidence row.
+
+### Audit and Data Safety
+
+#### Report Output
+
+- Report filename templates now reject empty names, `..` path traversal components, `/`, `\`, and path-shaped templates before writing files.
+- `AuditRunner` uses the same report filename validation before report output is written.
+- Report template names such as `team..1-{dir}-{date}.html` remain valid because only actual path traversal components are rejected.
+
+#### Evidence Bundle Export
+
+- Evidence Bundle export now writes to a temporary ZIP first and replaces the destination only after the archive is complete.
+- Exporting to a directory path is rejected without deleting existing content.
+- Existing files are no longer removed before a successful replacement is ready.
+
+#### Fingerprint Packages
+
+- Fingerprint package import now enforces JSON size limits.
+- ZIP fingerprint entries have per-entry size limits.
+- Fingerprint packages have a record count limit before import.
+- Oversized packages fail early instead of consuming unbounded memory or database work.
+
+#### PDF and Document Handling
+
+- Zero-page PDFs now return an empty embedded-image result instead of failing the image extraction path.
+- Existing Office and document ingestion limits remain in place for archive entry safety.
+
+#### Local Assistant Commands
+
+- Local helper commands now execute from background tasks instead of blocking UI-facing code paths.
+- Helper processes launch in their own process group.
+- Cancellation and timeout cleanup terminate child processes, including children that outlive the parent shell.
+- Termination waits no longer use blocking `Thread.sleep` loops.
+
+### Updates and Release Pipeline
+
+#### Beta Appcast Safety
+
+- Release workflow runs are serialized so beta appcast publishing cannot overlap with another release run.
+- Beta and RC builds use the fixed `appcast-beta` URL instead of GitHub Latest.
+- The workflow validates that the local appcast points at the current beta or RC tag before upload.
+- The workflow validates the uploaded `appcast-beta` asset after upload.
+- Older beta or RC tags are refused when the existing beta channel already points at a newer prerelease.
+
+#### Silent Update State
+
+- Silent update check failures preserve the existing `availableUpdate` state.
+- A transient network or feed failure no longer clears the left-side update prompt when an update was already detected.
+
+#### CI and Artifact Uploads
+
+- GitHub Actions artifact upload now uses `actions/upload-artifact@v7.0.1`, which runs on Node.js 24.
+- CI no longer repeats the full Swift test suite through the flaky SwiftPM `swiftpm-testing` runner on GitHub-hosted macOS.
+- SwiftPM still builds the package and test targets through `swift build --build-tests`.
+- The full test gate remains the Xcode test step.
+- The duplicate `swift test --parallel` lightweight smoke step was removed after repeated GitHub runner timeouts.
+
+### Validation
+
+Validation completed before preparing this release included:
+
+- `git diff --check`
+- `ruby -e 'require "yaml"; YAML.load_file(".github/workflows/ci.yml"); YAML.load_file(".github/workflows/release.yml")'`
+- `ruby -e 'require "json"; JSON.parse(File.read("PitcherPlantApp/Resources/Localizable.xcstrings"))'`
+- beta appcast workflow shell syntax check with `bash -n`
+- `swift build --package-path PitcherPlantApp --build-tests`
+- `xcodebuild -project PitcherPlantApp/PitcherPlantApp.xcodeproj -scheme PitcherPlantApp -destination 'platform=macOS' test`
+- GitHub CI on `master` after the CI stabilization change
+- Release workflow dry-runs for beta-channel packaging and appcast generation
+- Verification that the generated beta appcast URL uses `appcast-beta`
+- Verification that older beta tags are refused before replacing a newer `appcast-beta` asset
+
+### Distribution Notes
+
+- This is a beta release. It is intended for validating the native macOS audit workflow before a stable release.
+- Public artifacts may be ad-hoc signed and not notarized when Developer ID signing secrets are not used.
+- The expected release assets are ZIP, DMG, Sparkle appcast, xcarchive ZIP, dSYM archive, and SHA-256 checksums.
+- The DMG contains `PitcherPlant.app` and an Applications drag-and-drop shortcut.
+- macOS Gatekeeper may require Control-click > Open, System Settings > Privacy & Security > Open Anyway, or removing quarantine for local testing.
+- Sparkle automatic update installation requires clients that already contain the Sparkle EdDSA public key. Older builds without that key may need a manual install before automatic beta updates can be tested.
+
+### Known Notes
+
+- The app remains macOS 26+ only.
+- The current beta distribution path does not represent Apple Developer ID notarized distribution.
+- Some Swift compiler warnings related to older macOS APIs may still appear in logs, but they do not block the current beta build or test flow.