From 207bef743e0290d27ad32c3c7302084aefb79612 Mon Sep 17 00:00:00 2001 From: Patrick Schiller Date: Sat, 1 Aug 2026 11:29:16 +0200 Subject: [PATCH] Document the SourceBraid 1.0 release gates Signed-off-by: Patrick Schiller --- docs/RELEASE_CHECKLIST.md | 160 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 160 insertions(+) create mode 100644 docs/RELEASE_CHECKLIST.md diff --git a/docs/RELEASE_CHECKLIST.md b/docs/RELEASE_CHECKLIST.md new file mode 100644 index 0000000..bfb6fcd --- /dev/null +++ b/docs/RELEASE_CHECKLIST.md @@ -0,0 +1,160 @@ +# SourceBraid 1.0 release checklist + +This checklist turns the four publication tracks into reviewable release gates. +Store dashboards, identity verification, legal attestations, credentials, and +the final **Submit** actions remain manual account-owner steps. + +## 0. Establish the release commit + +- Reconcile the private `main`, `origin/main`, and public `public/main` before + bumping versions. Never publish the current private checkout while it is + behind the public branch or contains unrelated uncommitted work. +- Select one release commit and tag. If this is the first non-beta release, + align the customer-facing versions at `1.0.0`; iOS build numbers remain + monotonically increasing. +- Export the public release through the existing explicit public-file allowlist. + Never copy `website/`, `web-clips/`, private Git history, credentials, caches, + or build artifacts into the public repository. +- Run the core Node and Python suites and the unsigned iOS build from + `AGENTS.md`. + +## 1. Chrome Web Store + +### Release artifact + +```bash +python3 scripts/build_chrome_package.py +unzip -l dist/sourcebraid-chrome-v*.zip +``` + +The builder places `manifest.json` at the ZIP root and includes only 15 known +runtime/PDF-support files. It excludes the private archive, website, iOS project, +plugin config, Git data, tests, caches, and local configuration. + +Before building, ensure the manifest version is greater than every previously +uploaded version. The public branch currently contains `0.7.1`, while the +private checkout inspected during this preparation still contained `0.7.0`. + +### Listing material + +- Category: `Productivity`. +- Single purpose: "Save the page, paper, wiki, Gist, or PDF explicitly selected + by the user as portable Markdown in the user's own GitHub repository." +- Required graphics: 128×128 PNG store icon, at least one 1280×800 screenshot, + and a 440×280 small promo tile. The existing 1200×675 marketing screenshots + do not meet the Chrome screenshot dimensions and must not be uploaded as-is. +- Recommended screenshots: capture popup/settings, a completed GitHub archive, + PDF conversion, and fallback download using only synthetic data. +- Homepage: `https://sourcebraid.com`. +- Support: `https://github.com/patrickschiller/sourcebraid/issues`. +- Privacy: `https://github.com/patrickschiller/sourcebraid/blob/main/PRIVACY.md`. + +### Privacy and permission declarations + +- `activeTab`: inspect only the tab on which the user invokes SourceBraid. +- `scripting`: run the packaged capture script in that selected tab. +- `storage`: store repository settings, fine-grained token, optional source API + keys, tags, and UI preferences locally in extension storage. +- `downloads`: save the explicit Markdown/config fallback selected by the user. +- ``: read the selected source and its linked content assets or source + APIs across origins; SourceBraid does not monitor tabs in the background. +- `https://api.github.com/*`: upload the user-confirmed capture directly to the + configured repository and read/update its metadata shard. +- Remote code: **No**. All executable JavaScript is packaged in the extension; + fetched page data and APIs are treated as data. +- Disclose at least authentication information, website content, the selected + page URL/browsing activity, and user-provided notes/tags. State that data is + used only for the user-facing capture workflow and sent directly to the + configured GitHub repository. + +Upload the ZIP in the [Chrome Developer Dashboard](https://chrome.google.com/webstore/devconsole), +complete Store Listing, Privacy, Distribution, and Test Instructions, then use +deferred publishing so approval and launch can be separated. + +## 2. ChatGPT and Codex plugin + +Build the initial public **Skills only** package: + +```bash +python3 scripts/build_plugin_package.py +unzip -l dist/sourcebraid-plugin-skills-v*.zip +python3 /path/to/plugin-creator/scripts/validate_plugin.py codex-plugin/sourcebraid +``` + +The release ZIP intentionally removes the local `.mcp.json` reference and MCP +server. It contains the three skills, their OpenAI metadata, the dependency-free +CLI, and listing assets. Local/repo marketplace installs keep the bundled MCP +server. This avoids introducing a central SourceBraid service merely for +publication. + +Submission prerequisites: + +- OpenAI Platform organization role with **Apps Management: Write**. +- Verified individual or business developer identity matching the website and + legal/support URLs. +- Final logo, descriptions, starter prompts, country availability, and release + notes. +- Five positive test cases: status/config guidance; first index build; search + and fetch with citations; incremental index update; deletion preview followed + by a separate exact confirmation. +- Three negative test cases: refuse deletion without a fresh preview; refuse a + stale deletion after the branch head changes; do not browse the public web as + a substitute for an unavailable private archive. + +Create a **Skills only** draft in the +[OpenAI plugin submission portal](https://platform.openai.com/plugins), upload +the package, complete the test cases and attestations, submit for review, and +publish the approved version. One publication lists it in the universal +directory shared by ChatGPT and Codex. + +## 3. iOS App Store + +- Preserve the existing App Store/TestFlight identifiers + `de.patrickschiller.stowmark` and `de.patrickschiller.stowmark.share`, the + shared App Group, and Keychain group. Changing them would create a new app and + break the existing migration path. +- Confirm the customer-facing version and increment `CURRENT_PROJECT_VERSION` + beyond the latest uploaded build for both app and Share Extension. +- Run the unsigned simulator build, then archive and upload with the commands in + `ios/README.md` using a current supported Xcode. +- Product metadata: name, subtitle, description, keywords, primary category, + support URL, marketing URL, copyright, price/availability, age rating, content + rights, and EU Digital Services Act trader status. +- Upload real in-use screenshots for each required device class/localization, + using only synthetic repository names and captures. +- App Privacy: provide the public privacy-policy URL and answer the label for all + data sent to GitHub. Review user content/files, GitHub account identifiers, + repository metadata, and credentials as app-functionality data; do not claim + "no data collected" merely because SourceBraid itself has no central server. +- App Review notes: explain the Share Extension, direct GitHub data flow, token + storage in Keychain, PDF workflow, and how to test. Provide a dedicated demo + private repository and non-expiring review token through App Store Connect, + never in source control. +- Confirm export compliance (`ITSAppUsesNonExemptEncryption = false`), select the + processed build, add it for review, submit the draft, and choose manual release + for launch coordination. + +## 4. Automatic GitHub setup + +Prerequisite: install `gh` and run `gh auth login` with an account allowed to +create the target repository and manage Actions. + +```bash +python3 scripts/setup_github.py --repo OWNER/sourcebraid-private --dry-run +python3 scripts/setup_github.py --repo OWNER/sourcebraid-private +``` + +The script: + +- creates a private repository when absent and refuses an existing public one; +- enables Actions; the bundled workflow itself requests only + `contents: write` for PDF conversion commits; +- uploads only the Docling workflow, conversion scripts, requirements, and an + empty archive placeholder; +- preserves every existing file by default; and +- never creates, prints, or stores a GitHub access token. + +After setup, create a fine-grained client token restricted to that repository +with `Contents: Read and write`. `Workflows: Read and write` is needed only when +the Chrome extension must install the workflow itself instead of using this +setup script.