Repository navigation
docs: document per-platform install and download steps - #228
Merged
HsiangNianian merged 3 commits intoOct 23, 2026
Merged
HsiangNianian merged 3 commits into
HsiangNianian merged 3 commits into
Conversation
Contributor
Reviewer's GuideThis documentation-focused PR makes release installation discoverable in the README and detailed guides by documenting package selection and installation across supported platforms, including RPM, AUR, and Alpine musl distributions, with provenance and verification guidance. File-Level Changes
Assessment against linked issues
Possibly linked issues
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
Contributor
📦 Semifold release planPlan calculated through commit 5467ca5. Changesets introduced by this pull request: 1 changesets · 1 packages
This comment updates automatically as the pull request changes. |
HsiangNianian
approved these changes
Oct 21, 2026
fu050409
reviewed
Oct 21, 2026
Contributor
There was a problem hiding this comment.
@hydroroll-bot 为@dropout/docs生成patch级别的变更集来记录文档更新
Member
Author
|
回应审查意见（@fu050409）：
逐条处理
关于自查提示「
|
Contributor
There was a problem hiding this comment.
🟢 Approval recommended
The documentation changes are focused and consistent with release packaging, with only a non-blocking safety improvement remaining.
1 open issue
What changed in this PR
Makes installation guidance discoverable in both READMEs, addressing #227 across supported platforms.
Changes:
- Adds download links, platform-specific installation steps, and verification guidance.
- Expands both getting-started guides with RPM and AUR instructions.
- Adds a documentation changelog entry.
| File | Description |
|---|---|
| README.md | Adds English installation and verification guidance. |
| README.CN.md | Adds equivalent Chinese installation guidance. |
| packages/docs/content/zh/manual/getting-started.mdx | Documents RPM and AUR installation in Chinese. |
| packages/docs/content/en/manual/getting-started.mdx | Documents RPM and AUR installation in English. |
| .changes/document-per-platform-install.md | Records the documentation update. |
Review effort: Balanced
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Hey - I've found 7 issues
Prompt for AI Agents
Please address the comments from this code review:
## Individual Comments
### Comment 1
<location path="README.md" line_range="83" />
<code_context>
+|---|---|---|---|
+| Windows 10/11 | x86_64, ARM64 | NSIS `-setup.exe` | Run the installer, then launch DropOut from the Start menu. |
+| macOS | Apple Silicon, Intel | `.dmg` | Open the disk image and drag DropOut into `Applications`. If macOS blocks the first launch, allow it in System Settings → Privacy & Security. |
+| Debian / Ubuntu | x86_64, ARM64 | `.deb` | `sudo dpkg -i Dropout_*.deb`, then `sudo apt-get install -f` if dependencies are missing. |
+| Fedora / RHEL | x86_64, ARM64 | `.rpm` | `sudo dnf install ./Dropout-*.rpm` |
+| Any glibc Linux | x86_64, ARM64 | `.AppImage` | `chmod +x Dropout_*.AppImage && ./Dropout_*.AppImage` |
</code_context>
<issue_to_address>
**Unintended packages run as root**
When the working directory contains stale, other-architecture, or untrusted packages matching the globs, `sudo dpkg -i Dropout_*.deb` and `sudo dnf install ./Dropout-*.rpm` expand every match. They can install an older package, fail partway through, or install an unintended package and run its scripts as root.
Use the exact intended package filename in each command instead of a wildcard.
Also at `README.md:84`, `README.CN.md:83-84`, `packages/docs/content/en/manual/getting-started.mdx:48`, `packages/docs/content/zh/manual/getting-started.mdx:48`.
</issue_to_address>
### Comment 2
<location path="README.md" line_range="101" />
<code_context>
+
+```bash
+sudo apk add ca-certificates gtk+3.0 libayatana-appindicator librsvg openssl webkit2gtk-4.1
+sha256sum -c Dropout_*-musl.tar.gz.sha256
+tar -xzf Dropout_*-musl.tar.gz
+cd Dropout_*-musl
</code_context>
<issue_to_address>
**Checksum failures do not stop execution**
When the archive checksum does not match, the shell continues to `tar`, `cd`, and run `./dropout` after `sha256sum -c` reports a mismatch, so a corrupted or tampered archive is still executed when users paste the full block.
Add `set -e` at the start of each block or chain verification, extraction, and execution so a failed check stops the sequence.
Also at `README.CN.md:101`.
</issue_to_address>
### Comment 3
<location path="README.md" line_range="94" />
<code_context>
+所有桌面安装包都带有签名构建来源证明，安装前可以校验它确实由本仓库的发布流程产出：
+
+```bash
+gh attestation verify ./downloaded-asset -R HydroRoll-Team/DropOut
+```
+
</code_context>
<issue_to_address>
**Provenance accepts unrelated workflows**
When a non-release workflow in HydroRoll-Team/DropOut attests an unintended or malicious asset, a user verifying a downloaded asset runs `gh attestation verify` with only `-R HydroRoll-Team/DropOut`, which restricts the repository but not the signing workflow. An asset attested by another workflow in that repository therefore passes and is presented as produced by the release workflow.
Constrain verification to the trusted release workflow (for example, with `--signer-workflow`) and update the provenance check to require that constraint.
Also at `README.CN.md:94`.
</issue_to_address>
### Comment 4
<location path="README.md" line_range="86" />
<code_context>
+| Debian / Ubuntu | x86_64, ARM64 | `.deb` | `sudo dpkg -i Dropout_*.deb`, then `sudo apt-get install -f` if dependencies are missing. |
+| Fedora / RHEL | x86_64, ARM64 | `.rpm` | `sudo dnf install ./Dropout-*.rpm` |
+| Any glibc Linux | x86_64, ARM64 | `.AppImage` | `chmod +x Dropout_*.AppImage && ./Dropout_*.AppImage` |
+| Arch Linux | x86_64, ARM64 | AUR `dropout-bin` | `yay -S dropout-bin` (or `paru -S dropout-bin`) |
+| Alpine Linux 3.22 | x86_64 | `-musl.tar.gz` | Install the runtime libraries, verify the checksum, extract, and run `./dropout` (see below). |
+
</code_context>
<issue_to_address>
**Arch installs lack tray support**
When a user installs the AUR package on a clean Arch system without the AppIndicator runtime library, the generated AUR package omits `libayatana-appindicator`, even though the launcher uses Tauri’s tray API. Without that library the tray integration cannot initialize, leaving the app without its documented system-tray functionality.
Add `libayatana-appindicator` to the dependencies declared by the generated AUR package.
Also at `README.CN.md:86-87`, `packages/docs/content/en/manual/getting-started.mdx:58-64`, `packages/docs/content/zh/manual/getting-started.mdx:58-64`.
</issue_to_address>
### Comment 5
<location path="README.md" line_range="85" />
<code_context>
+| macOS | Apple Silicon, Intel | `.dmg` | Open the disk image and drag DropOut into `Applications`. If macOS blocks the first launch, allow it in System Settings → Privacy & Security. |
+| Debian / Ubuntu | x86_64, ARM64 | `.deb` | `sudo dpkg -i Dropout_*.deb`, then `sudo apt-get install -f` if dependencies are missing. |
+| Fedora / RHEL | x86_64, ARM64 | `.rpm` | `sudo dnf install ./Dropout-*.rpm` |
+| Any glibc Linux | x86_64, ARM64 | `.AppImage` | `chmod +x Dropout_*.AppImage && ./Dropout_*.AppImage` |
+| Arch Linux | x86_64, ARM64 | AUR `dropout-bin` | `yay -S dropout-bin` (or `paru -S dropout-bin`) |
+| Alpine Linux 3.22 | x86_64 | `-musl.tar.gz` | Install the runtime libraries, verify the checksum, extract, and run `./dropout` (see below). |
</code_context>
<issue_to_address>
**AppImage fails without FUSE 2**
When a user runs the documented AppImage command on a glibc system without FUSE 2, `./Dropout_*.AppImage` tries to mount the image and exits with a FUSE error before DropOut starts. The instructions provide no prerequisite or extraction fallback, so users cannot launch it using those steps.
Document the FUSE 2 prerequisite or provide an extraction-based launch fallback.
Also at `README.CN.md:85`, `packages/docs/content/en/manual/getting-started.mdx:52`, `packages/docs/content/zh/manual/getting-started.mdx:52`.
</issue_to_address>
### Comment 6
<location path="README.md" line_range="100" />
<code_context>
+Alpine Linux 需要先安装原生 WebKitGTK 运行库，musl 包才能运行：
+
+```bash
+sudo apk add ca-certificates gtk+3.0 libayatana-appindicator librsvg openssl webkit2gtk-4.1
+sha256sum -c Dropout_*-musl.tar.gz.sha256
+tar -xzf Dropout_*-musl.tar.gz
</code_context>
<issue_to_address>
**Alpine dependency command fails**
When a standard Alpine installation has no `sudo` package installed, `sudo apk add ...` exits with `sudo: not found`, so readers on a standard Alpine installation cannot install the required runtime libraries using the documented command and cannot continue launching the archive.
Show the command run as root (or explain how to use `doas`/install `sudo` first).
Also at `README.CN.md:100`.
</issue_to_address>
### Comment 7
<location path="README.md" line_range="91" />
<code_context>
+
+Asset names embed the version and architecture, for example `Dropout_0.2.0-rc.2_amd64.AppImage`; pick the file matching your OS and your CPU suffix (`x64`/`amd64`/`x86_64` or `arm64`/`aarch64`).
+
+Every desktop asset has signed GitHub build provenance, so you can verify that it came from this repository's release workflow before installing:
+
+```bash
</code_context>
<issue_to_address>
**AUR package lacks attestation**
When a user installs `dropout-bin` from the AUR and interprets the provenance claim as covering that package, the AUR package is included in the installation list covered by the provenance claim, but it is built through the AUR `PKGBUILD`, not published as an attested GitHub release artifact; users cannot verify the installed AUR package with the documented command, despite being told its provenance is covered.
Limit the provenance claim to GitHub release artifacts and explain separately how AUR users can verify the package’s upstream source artifact and PKGBUILD.
Also at `README.CN.md:91`, `packages/docs/content/en/manual/getting-started.mdx:20`, `packages/docs/content/zh/manual/getting-started.mdx:20`.
</issue_to_address>Sourcery assessment
Approval pending. 7 findings to address first.
Blocking findings: README.md:83, README.md:101, README.md:94, README.md:86, README.md:85, and 2 more
HsiangNianian
approved these changes
Oct 22, 2026
HsiangNianian
enabled auto-merge
October 22, 2026 01:39
Add Windows, macOS, Debian/Ubuntu, Fedora/RHEL, AppImage, AUR and Alpine musl install/download steps to the getting-started guide, along with asset verification and first-launch troubleshooting.
Add a changeset entry so the per-platform install documentation lands as a @dropout/docs chore release.
Update the Alpine musl install snippet in README.md so the download, extraction and launch commands run correctly.
HsiangNianian
disabled auto-merge
October 23, 2026 04:00
Member
|
@hydroroll-bot 所有提交重新签名一下 |
Member
check |
Member
Author
|
在后台重签了，PR #228 分支上所有提交都会重新签一遍再推上去，代码内容不动。弄完我在 PR 里回你。 |
Member
|
@hydroroll-bot 先停掉重签任务 j8d69a3，别推 |
Member
Author
|
已停掉 需要的话我可以再确认一下远端分支的当前 SHA，或者换个思路重来。 |
HsiangNianian
enabled auto-merge
October 23, 2026 04:12
Member
@hydroroll-bot 没事，继续吧 |
Member
Author
|
收到。我重新启动了一个任务（ |
Member
Author
|
重写提交完成:文件内容一行未改,只重建了提交本身(作者/提交者统一为 历史
验证(可复现) 只有 Markdown 改动,没有代码可跑;没碰 CI 和权限。 对自查三条的回复
原提交的
推送:历史被重写,需要 force push,只推 重写了分支历史（force push）：现在 3 个提交，重建并签名了 3 个（chore(docs): rewrite branch commits onto bot identity for signing）。 |
hydroroll-bot
force-pushed
the
krypton/docs-document-per-platform-install-and-d-j42c0ff
branch
from
October 23, 2026 04:21
7f5533c to
5467ca5
Compare
Member
Author
|
@HsiangNianian 重签完了，PR: #228 三个提交都重写了，作者/提交者统一成 hydroroll-bot，推送时用 bot 的 SSH key 签名，GitHub 上会显示 Verified。历史和原来一样是 3 个提交，没 squash、没 rebase，基准还是 main 的 需要你看一下的是验证部分：新旧提交的 tree 逐一是同一个哈希， |
HsiangNianian
deleted the
krypton/docs-document-per-platform-install-and-d-j42c0ff
branch
October 23, 2026 04:29
Member
|
@hydroroll-bot 傻氪帮我 roll 个 3d6 |
Member
Author
|
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #227
What
Answers #227 ("怎么安装、怎么下载，全平台") by making installation discoverable where users actually look.
README.md/README.CN.md: new## Install/## 安装section with a per-platform table:-setup.exe.dmg, plus the Gatekeeper allow step.deb+apt-get install -ffallback.rpmviasudo dnf install ./Dropout-*.rpm(resolves webkit2gtk4.1 / appindicator deps and upgrades cleanly, unlikerpm -i).AppImagedropout-bin-musl.tar.gzwith theapk addruntime libs, checksum check, and run steps taken frompackaging/linux-musl/README.mdx64/amd64/x86_64andarm64/aarch64suffixes (Windows NSIS and macOS Intel dmg usex64),gh attestation verifyprovenance check, a pointer that Rust/Node are only needed for source builds, and links to the English/Chinese getting-started docs.packages/docs/content/{en,zh}/manual/getting-started.mdx: add.rpmto both the x86_64 and ARM64 download rows, add the AURdropout-binrow and "Using .rpm Package" / "Using AUR Package" subsections, and update the glibc-vs-musl sentence to mention rpm/AUR. AUR support already exists inscripts/release-aur.ts(arch=('x86_64' 'aarch64'), published from the release workflow) but was undocumented.Why README
The docs already had Linux/macOS/Windows install pages, but the README only had a developer Quick Start — a user who "read the README" still had no download link or platform table, which is what #227 reports.
Verification
node --test scripts/parity-audit.test.mjs→ 3/3 pass.git diff --checkclean; table column counts checked in both READMEs (4 columns) and both docs tables (2 columns)..github/workflows/semifold-ci.yaml(deb/rpm/AppImage on both GNU targets, dmg for both macOS arches, NSIS for x64 + ARM64), AUR arch/source inscripts/release-aur.ts, Alpine apk deps inpackaging/linux-musl/README.md, docs URL indocs/cloudflare-deployment.md.Not run locally: the docs site build (
pnpm --dir packages/docs build, needs network forpnpm install), markdownlint/prettier (not installed in the sandbox), andscripts/release-workflow.test.mjs(fails withERR_MODULE_NOT_FOUND: js-yaml— missing node_modules, pre-existing and unrelated to this change).No changelog fragment added:
.changesholds onlyconfig.tomland changesets appear to be generated from commits.由 Krypton（hydroroll-bot）处理 #227（HsiangNianian 打上了 krypton 标签）自动生成，是草稿，需要人审查后再合并。
Summary by Sourcery
Document platform-specific download and installation paths so users can install DropOut directly from the README and getting-started guides.
New Features:
Enhancements:
Documentation: