From ed3477d1b3a4ce64999ab614db3d76ce3656d5ec Mon Sep 17 00:00:00 2001 From: Nils Pukropp Date: Tue, 6 Oct 2026 19:29:02 +0200 Subject: [PATCH] docs: point contributors at the simulation runs and the ledger rules DEVELOPMENT.md lists the daemon's current modules, asks for the simulation runs on FUSE, queue and sync changes, and adds how to handle a bug fix and a user-visible change, including the six pages the wiki publisher copies. The release checklist moves to TESTING.md. --- CONTRIBUTING.md | 6 +++--- docs/DEVELOPMENT.md | 22 ++++++++++++++++------ 2 files changed, 19 insertions(+), 9 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index fcb4ce5..b578671 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -39,9 +39,9 @@ cargo test --workspace --locked scripts/fuse-acceptance.sh --offline-only ``` -Changes to the FUSE layer, sync, or the pending-operation queue should also be exercised against a -real mount before review — see [`docs/TESTING.md`](docs/TESTING.md). Live runs are destructive: -use a dedicated test account, never one holding data you cannot lose. +Changes to the FUSE layer, sync, or the queue should also pass the simulation runs and be +exercised against a real mount before review — see [`docs/TESTING.md`](docs/TESTING.md). Live +runs are destructive: use a dedicated test account, never one holding data you cannot lose. ## Making changes diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.md index 8a6f4c8..2844758 100644 --- a/docs/DEVELOPMENT.md +++ b/docs/DEVELOPMENT.md @@ -31,12 +31,12 @@ time when the installed library has them (`crates/pdfs-gui/src/compat.rs`). | Path | Contents | |---|---| | `crates/pdfs-core` | Shared library: authentication and keyring (`auth`), configuration (`config`), SQLite schema and queries (`db/`), content cache (`cache`), control protocol (`control`), search scoring, sync ignore rules, Google Takeout parsing, machine profile | -| `crates/pdfs-fuse` | The daemon: FUSE filesystem, read path (`reads`), write queue (`queue`, `drain`, `upload`), sync engine (`sync/`), remote events (`background`), push events for front ends (`events`), control handlers (`control`), photos, devices, supervisor | +| `crates/pdfs-fuse` | The daemon: FUSE handlers (`filesystem`), the tree (`state`), reads (`reads`), the queue and the drain (`queue`, `drain`, `upload`), link state (`link`), the sync engine (`sync`, `sync/`), moves between locations (`relocate`), remote events (`background`), push events (`events`), control handlers (`control`), photos, devices, the supervisor, and the simulation tests (`sim/`) | | `crates/pdfs-cli` | The `pdfs` binary | | `crates/pdfs-gui` | `pdfs-app`, `pdfs-tray` and `pdfs-prompt`. Pages in `src/app/pages/`, shared widgets in `src/app/widgets/`, CSS and icons in `resources/` | | `po/` | Translation template, catalogs and the scripts that maintain them | | `packaging/` | systemd unit, desktop files, icon, PKGBUILD, RPM spec, AUR recipes | -| `scripts/` | FUSE acceptance suite, map-data generators | +| `scripts/` | FUSE acceptance suite, map-data generators, the wiki publisher | | `docs/` | This documentation | The GUI talks to the daemon only through the control socket. Anything a front end needs that the @@ -87,8 +87,9 @@ cargo test --workspace --locked scripts/fuse-acceptance.sh --offline-only ``` -For changes to the FUSE layer, the write queue or the sync engine, also run the live acceptance -cases described in [TESTING.md](TESTING.md). +For changes to the FUSE layer, the queue or the sync engine, also run the +[simulation runs](TESTING.md#simulation-runs), which CI runs only after a push to `main`, and the +[acceptance suite](TESTING.md#acceptance-suite) on a test account. For changes to GUI strings, check that every catalog is complete: @@ -136,6 +137,15 @@ file to `po/POTFILES.in`, run `po/update.sh`, and translate the new entries in e `#[serde(default)]`, so older files still load, and document it in [CONFIGURATION.md](CONFIGURATION.md). +**A bug fix.** Add or update the entry in [BUGS.md](BUGS.md#adding-an-entry), cover the fix with a +unit test, a simulation scenario or a `regression B` acceptance case, and cite the entry in the +code as `docs/BUGS.md B`. Do not cite planning notes that are not in the repository. + +**A user-visible change.** Update the matching page (user guide, CLI reference, configuration) +and the `[Unreleased]` section of [CHANGELOG.md](CHANGELOG.md). `scripts/publish-wiki.sh` copies +the six user pages (`INSTALL`, `USER_GUIDE`, `CLI`, `CONFIGURATION`, `TROUBLESHOOTING`, `RECOVERY`) +to the GitHub wiki, so keep their file names. + ## Releasing Releases are cut from `main` by pushing a `v*` tag. `.github/workflows/release.yml` then: @@ -160,5 +170,5 @@ git tag vX.Y.Z git push origin main vX.Y.Z ``` -Before a release that touches the filesystem or sync, run the managed live mode matrix from -[TESTING.md](TESTING.md). Open release-assurance items are listed in [ROADMAP.md](ROADMAP.md). +Before a release, work through [Before a release](TESTING.md#before-a-release). Open +release-assurance items are listed in [ROADMAP.md](ROADMAP.md#release-assurance).