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.tomlchecks 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 offeringApache-2.0 OR GPL-2.0-onlycan still pass using Apache-2.0. - RustSec:
cargo-denyfetches 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 passescheck --warn unmaintainedfor 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, notui-testsor an all-platform lockfile inventory. Build dependencies are retained (CycloneDX marks themexcluded, 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.