Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Development

Checks

cargo fmt --all --check
cargo test --locked --no-default-features
cargo test --locked --features ui-tests
cargo check --locked
cargo clippy --locked --all-targets --all-features -- -D warnings
uv run --locked python -m unittest discover -s tools -p 'test_*.py'
uv run --locked python tools/supply_chain.py

Core and storage tests need no graphical environment. The ui-tests feature runs GPUI’s test platform without opening windows.

Optimized local builds

The release profile uses fat LTO and a single code-generation unit for the smallest, fastest packages, so large crates and the final link compile on one core and take minutes. For an optimized build to try locally, use the fast-release profile instead; thin LTO and parallel code generation use every core, at the cost of a slightly larger and marginally slower binary:

cargo run --profile fast-release --locked

Its output is in target/fast-release/. Packaging and CI keep using release. To see which crate is compiling, add -v; cargo build --timings writes a report to target/cargo-timings/.

Python tooling with uv

Install uv 0.11.30 or newer. From the repository root, uv run --locked python … creates .venv/ and uses the Python 3.13 series selected by .python-version, downloading it if needed. No manual environment activation or global pip install is needed. pyproject.toml and the committed uv.lock define the tooling environment; --locked refuses dependency changes rather than rewriting the lockfile.

Normal checks, packaging, and SBOM helpers use only the standard library. The optional icons group contains Pillow (Python 3.11+):

uv sync --locked                         # prepare the standard tooling environment
uv lock --check                          # verify metadata and lockfile agree
uv run --locked --group icons python tools/generate_icons.py

Icon generation rewrites committed branding files; it is not part of ordinary builds. To change Python dependencies intentionally, use uv add --group icons … (or another appropriate group), or uv lock --upgrade-package pillow, and review both pyproject.toml and uv.lock. Rust crates and the pinned Cargo extensions are still managed by Cargo, not uv, and are not Python dependencies. Cargo’s SBOM and RustSec checks do not inventory or audit optional Python packages; their versions and archive hashes are recorded separately in uv.lock.

CI bootstraps uv 0.11.30 into .ci-tools/bin/ without modifying shell profiles, checks the lockfile, and uses the same locked commands. Per-job tool caches retain uv, managed Python, and .uv-cache/; .venv/ is recreated, not cached. The SAST and Secret Detection jobs remain independent of this environment.

Dependency licenses, RustSec, and SBOMs

Install the pinned tools explicitly (into the ignored .ci-tools/ directory), then run the same workflow as CI:

uv run --locked python tools/supply_chain.py install
uv run --locked python tools/supply_chain.py

The runner requires cargo-deny 0.20.2 and cargo-cyclonedx 0.5.10. Normal checks never install tools, build or launch the app, or access task data. They need network access to fetch crate metadata and the current RustSec database.

  • Licenses: dependency_policy.toml checks normal, build, and dev dependencies with all application features across arm64/x86-64 macOS and GNU/Linux. Its explicit allowlist captures the existing dependency baseline: 0BSD, Apache-2.0, BSD-2-Clause, BSD-3-Clause, CC0-1.0, ISC, MIT, Unicode-3.0, and Zlib. Existing MPL-2.0 dependencies have exact-version exceptions, not blanket approval. New licenses, unlicensed dependencies, and MPL upgrades require review. GPL/AGPL/LGPL/EPL are not approved; a crate offering Apache-2.0 OR GPL-2.0-only can still pass using Apache-2.0.
  • RustSec: cargo-deny fetches the community-maintained RustSec advisory database and checks the same dependency graph. Known vulnerabilities, unsoundness, and yanked releases fail the check; unmaintained-crate advisories are visible warnings. The runner passes check --warn unmaintained for this distinction. There are no advisory exemptions. This detects published advisories, not every vulnerability or abandoned crate. Existing maintenance warnings in the GPUI/Mermaid dependency trees need upstream replacements; they are not silently suppressed.
  • SBOM: CycloneDX 1.6 JSON describes the desktop binary’s transitive Cargo dependencies for the host target with exactly --no-default-features --features desktop, not ui-tests or an all-platform lockfile inventory. Build dependencies are retained (CycloneDX marks them excluded, rather than required at runtime). Components include license expressions, package URLs, registry archive checksums, and dependency relationships. Target, features, and the lockfile’s SHA-256 are recorded in metadata properties.

To scan an SBOM for known vulnerabilities as the release pipeline does, install the pinned Grype (0.121.1, checksum-verified, into .ci-tools/bin) and scan:

uv run --locked python tools/vulnerabilities.py install
uv run --locked python tools/vulnerabilities.py scan target/sbom/productivity-x86_64-unknown-linux-gnu.cdx.json

The report is target/vulnerabilities/grype.json; Grype downloads and caches its database in .ci-tools/grype-db. Findings are reported, not fatal. Upgrading Grype means updating GRYPE_VERSION and every pinned archive checksum in tools/vulnerabilities.py together.

The SBOM is generated, not committed: target/sbom/productivity-<target-triple>.cdx.json. Its application version comes from the current manifest, including CI’s stamped Ubuntu release version. Cargo validates locked resolution before generation; because cargo-cyclonedx has no --locked option, the runner also rejects lockfile changes before publishing the output. Basic identity/content checks are not full schema validation.

Individual operations:

uv run --locked python tools/supply_chain.py licenses
uv run --locked python tools/supply_chain.py advisories
uv run --locked python tools/supply_chain.py sbom --target x86_64-unknown-linux-gnu
# After building the matching desktop release, also identify its executable:
uv run --locked python tools/supply_chain.py sbom --binary target/release/productivity
# Inspect the crate/license inventory:
.ci-tools/bin/cargo-deny --locked --config dependency_policy.toml list --layout crate

Cross-target SBOM generation reads metadata; it does not cross-compile or prove that a target builds. --binary records the supplied executable’s SHA-256; the caller must supply the binary built with the documented target/features.

This is a Cargo dependency SBOM, not a complete inventory of bundled C sources, system libraries, the Rust standard library, fonts, icons, or packaging tools. In particular, bundled SQLite is represented by libsqlite3-sys, not as a separately inventoried SQLite component. Assets/native code and required license notices still need review. License checks are based on crate metadata and license files, not a legal determination.

Productivity itself is licensed under the Apache License 2.0. It is marked publish = false (not published to crates.io); the same policy checks its own license like every dependency’s.

Example data

Create a separate database with the example workspace, for screenshots or manual testing:

cargo run --locked --example seed_demo -- /tmp/productivity-demo/tasks.sqlite3
PRODUCTIVITY_DATA_DIR=/tmp/productivity-demo cargo run --locked

seed_demo refuses existing files, so it never touches real data.

Coverage

rustup component add llvm-tools-preview
cargo install cargo-llvm-cov --version 0.9.1 --locked
uv run --locked python tools/coverage.py

This writes an HTML report with function, line, and region coverage per file to target/coverage/html/, plus a Cobertura file. Branch coverage would need nightly Rust, which the project does not use.

Architecture

Workspace coordinates navigation and shared task/project data. Feature-local session state and initialization live in NotesState, TodayState, and CalendarState; shared project/type/status filters remain at workspace scope. These are plain owned structs, not independent stores or competing editor buffers.

Asynchronous results are matched to their request by an explicit identity (a generation counter plus the target note, library, or editor), never by the status text currently shown. Confirmations for destructive actions are their own state; a new status message disarms them but never authorizes them.

Rendering never parses note Markdown. The note editor advances one content generation per edit or source replacement; Live Edit formatting (src/ui/notes/live.rs) and the read-only preview (src/ui/notes/editor_preview.rs) are prepared off the UI thread after typing pauses and are applied only to the generation they were prepared from. Layouts without a preview pane skip preview preparation.

Task, project, planning, and workspace-replacement writes return the collections they committed, read inside the same transaction (for example TodayPlan, ProjectRemoval, WorkspaceData); the UI applies those results instead of reloading separately, so a failed reload can never be reported as a failed write. Immediate task changes (status, priority, project) go through Workspace::change_task, which refuses them over a dirty draft, persists first, and refreshes a clean editor from the saved task.

src/storage/database.rs owns connection settings, schema-version checks, and migrations for the one shared SQLite file. TaskStore and NoteStore each open their connection through it and do not depend on each other.

All screens use src/ui/screen_layout.rs for their date/title header, actions, status toolbar, content spacing/scroll container, errors, and footer. Supply screen-specific content and controls through its slots rather than building another header or toolbar frame. The editor density reduces padding and omits the subtitle; it cannot hide the current local day or title. Keep screen selection and task/note state in Workspace, not in the layout.

When adding a view, extend the cross-screen layout test. It checks shared header alignment, action bounds, and toolbar/content placement in normal and compact mode at 1000×640, 1320×840, and 1920×1200. Existing-note editing has the same coverage. Each screen also declares its ContentFit in Workspace::content_fit. Board-like screens (Today, Matrix, Kanban, Calendar, Notes Browse, Notes Write) Fill the space between toolbar and footer and scroll inside their own regions, so size them with flex_1().min_h_0() rather than fixed heights. Document-like screens Flow and scroll as a page. Either may scroll sideways when its minimum width exceeds the window. Layout tests check that every Fill screen ends above the footer at several sizes and that wide screens scroll horizontally.

src/
  core/          Task and project rules, dependencies, notes, settings types
  application/   TaskService and NoteService: the API used by the UI
  storage/       SQLite persistence, migrations, note indexing
  ui/            GPUI views and UI tests
  desktop/       Startup, menus, window setup, embedded assets
assets/          Icons and branding
packaging/       Platform launcher templates
tools/           Packaging, coverage, and icon helpers
book/            This documentation

Dependencies point UI → application → core/storage. The UI never touches SQLite, and the core builds without GPUI (--no-default-features) for future clients and sync adapters.

GPUI comes from gpui-pre and gpui-pre-platform, pinned to the exact snapshot that GPUI Component requires; upgrade them together.

Continuous integration

Pipelines currently run only when started from a GitLab pipeline schedule, to save compute minutes: create a schedule for main (it can stay inactive) and use its Run button. Pushes and merge requests do not start pipelines. To restore automatic pipelines, set the project CI/CD variable AUTO_PIPELINES to true (or change its default in .gitlab-ci.yml). Scheduled pipelines on main also package and publish Pages.

GitLab CI runs GitLab SAST and Secret Detection, the checks above on Linux, coverage, an Ubuntu 26.04 .deb, and this book. On main, Pages publishes the book together with the signed APT repository, coverage report, and release SBOM. The book’s opening page is the site landing page; existing book and APT URLs are unchanged. The coverage badge links to the latest successfully published HTML report.

macOS jobs are opt-in: set RUN_MACOS_CI=true once a macOS shell runner tagged macos is available (with GnuPG installed for the signing tests). They run the checks and build an unsigned .dmg. CI never signs or notarizes macOS builds and never installs anything.

The pages job signs the APT repository’s Release file with tools/apt_sign.py. The certify-only primary key is kept offline on a hardware token; CI holds only a signing subkey (APT_SIGNING_KEY, base64 of the armored export, and APT_SIGNING_PASSPHRASE), as protected, masked CI/CD variables scoped to the apt-signing environment. The job verifies InRelease and Release.gpg with gpgv against packaging/apt/productivity-archive-keyring.asc and fails without publishing if the variables are missing or the signature is wrong.

The supply-chain job gates both package jobs with license and RustSec checks, and uploads a host-target CycloneDX SBOM as an artifact/report. Each package job generates its own SBOM after building, with the actual release version and executable hash, and uploads it alongside its .deb/.dmg. The SBOM is a sidecar artifact, not embedded in those packages. Pages publishes the Ubuntu package job’s release SBOM, not the unstamped check-job SBOM. GitLab’s display/ingestion of CycloneDX reports depends on the server version and subscription.

tools/pages.py stages the book at the site root, HTML coverage and Cobertura XML under coverage/, the Ubuntu SBOM under sbom/, a current installer page under downloads/, and the package at its existing pool/ path. release-identity.json and SHA256SUMS identify the publication’s inputs. Checksums are not signatures. The staging step refuses an existing output directory, mismatched release/SBOM versions, wrong targets, missing executable hashes or reports, and stale packages. Pages explicitly downloads artifacts from book, coverage, and package-ubuntu in the same pipeline. The existing serialized deployment and latest-main guard remain.

To stage already-generated artifacts locally without installing or publishing:

uv run --locked python tools/pages.py --output target/pages-preview

Inputs default to the CI artifact locations; use --help to select other paths. The output must not exist. This assembles the site and package files; Linux CI then creates the dists/ APT metadata with dpkg-scanpackages and apt-ftparchive. It does not sign the repository or verify graphical installation. Report links will not resolve in a plain mdBook-only build.