Developer Guide

Developer guide

This page gets you from a fresh Windows PC to a running OpenNote window. It is a short version of CONTRIBUTING.md, which is the source of truth. Read that file before you open a pull request. By taking part, you agree to follow the code of conduct.

Set up on Windows

Install these tools once, in this order:

1. Microsoft C++ Build Tools, with the "Desktop development with C++" workload. Install it before Rust.
2. WebView2. It ships with Windows 10 and 11, so you usually have it.
3. Rust stable, through rustup, with the default stable-msvc toolchain.
4. Node.js 22.18 or newer, the long-term support release.
5. Git.

On macOS or Linux, install the Tauri prerequisites instead of steps 1 and 2.

Open a new terminal, then clone the repository and start the app:

git clone https://github.com/XrxcGH/OpenNote.git
cd OpenNote
npm install && npm start

The first start compiles the Rust dependencies, which takes several minutes. Later starts are much faster. Windows PowerShell 5.1 doesn't accept &&, so run npm install and npm start on separate lines there, or use PowerShell 7 or Command Prompt.

Also run this once, so CHECKS runs before each commit:

npm run setup-hooks

Everyday commands

Command	What it does
npm start	Runs the desktop app in development mode with live reload
npm test	Runs the CHECKS tests and the UI tests
npm run lint	Lints TypeScript and JavaScript
npm run typecheck	Type-checks all TypeScript
npm run format	Formats code with Prettier
npm run checks	Runs CHECKS on files changed since origin/main
npm run tokens	Regenerates the design tokens from brand/tokens.json
npm run build	Builds the release exe (requires CMake for audio encoding)

The full list of scripts, and the Rust commands, are in CONTRIBUTING.md. See Testing and quality for what each check covers.

The build process uses a shared build cache to speed up rebuilds. CMake (from Visual Studio Build Tools or installed separately) is required for the audio encoder. On most systems, Tauri will find these tools automatically.

Make a change

1. For a small fix, open a pull request right away. For a new feature, open an issue first, so everyone can agree that it fits the current phase.
2. Branch off the phase branch in progress. The current beta branch is beta, which holds Phases 5 to 12 being tested. Earlier phases branch from main and target main. See pull request #16 for how beta is merged.
3. Keep the pull request small, under about 400 changed lines, and add screenshots for visual changes in both themes.
4. Write the commit subject in the imperative mood, under about 72 characters.
5. Make sure every CI check passes, and get one approving review.

Details are in Development process.

Two rules to remember

• UI code uses design tokens only. To change how OpenNote looks, edit brand/tokens.json, run npm run tokens, and commit both together. Never edit the generated files by hand.
• Anything hard to reverse needs an architecture decision record before the code. See Design decisions.

Note file format and storage

The note file format is frozen and specified in docs/format/README.md in the repository. A notebook is a folder; sections are subfolders; each page is a folder with page.json (the source of truth), a readable page.md copy, and an assets/ folder for images and recordings. The crates/core library implements reading, writing, and atomic saves.

Crash recovery works in three sentences: edits reach a write-ahead journal before the page changes. If the app stops, the journal is replayed on the next open, bringing the page to the exact state it was in when the crash happened. The kill-harness test kills the app 1,000 times during saves and finds no damage.

To run the crash-safety test locally, build the optimized perf profile and run cargo crashtest measure all --dir /tmp, which will take time. Read the instructions in DEVELOPMENT.md for how to set up and run the full test suite.

Where to go next

• Architecture overview explains how the parts fit together.
• Repository map shows where things live.
• Testing and quality covers the CHECKS gate.
• Testing the beta guides people through hand testing each feature.
• Releasing is for maintainers.
• The development plan and the brand guide describe what to build and how it should feel.
• Report security problems privately, as the security policy describes.