Contributor manual
For anyone changing Inkhold’s code: how to build and test it, and why it is built the way it is.
Tutorials
Lessons: start here.
How-to
Steps for a task you have in mind.
- Run the tests Run the backend and web app suites, and the e2e tests in Chromium and WebKit.
- Run long test jobs in a container Run the full e2e suite and other long jobs in a container, not on your machine.
- Cross-build for every architecture Build for x86_64, aarch64, armhf (Raspberry Pi 1) and x86.
- Add a database migration Change the schema with a migration that upgrades every existing library.
- Add a file type Teach Inkhold to show, index and export a new kind of file.
- Measure memory and speed on a Pi Measure the server's footprint and a household's load on a real Raspberry Pi.
- Make a release Name the version, let CI build, test and publish it, soak it, then promote it.
- Write documentation Add or change a page, preview it, draw a diagram, and take its screenshots.
Reference
Facts to look up.
- Where things live The repository's map: which directory holds what, and how modules are split and named.
- Device protocol Every request the Supernote makes, and what Inkhold answers.
- HTTP API The web app's API: every route, its parameters and its answers.
- Database schema Every table and column, and the migrations that made them.
- Storage layout How files, versions and the bin are kept on disk, and the invariants that hold.
- Indexing and derived data The .note index, index_version, the derived stores, and what each format yields.
- Serving and caching How a page is planned and streamed, the cache rule, and the live channel.
- Search The index and its manifest, matching, ranking, coverage, find in a document, phrases and excerpts.
- Authentication and untrusted content The rules for passwords, sessions, admin elevation, and the files tablets send.
- Threads and locks Which thread may do what, the locks, and the route flags.
- Design language The web app's tokens, type, components and the rules every screen follows.
- The browser app Seams, routing, viewers, caches, export and the WebAssembly rules.
- Phones and offline Viewer bars, the phone layout, the bar that folds into ⋯, tablets, text size, installing and offline.
- Documentation rules
- Commit messages Conventional Commits: the types, the scopes, and the 120-character title.
Explanation
How it works, flow by flow, and the trade-offs behind each.
- The shape of the system One program at home, three faces on one port, and a browser that does the heavy work: how the pieces fit, and what that shape costs.
- What happens to a file From a tablet's upload to the disk, the bin, the version history and a backup: the life of a file, and the trade-offs along it.
- How the tablet syncs What happens between a Supernote and Inkhold, from sign-in to Auto Sync: the walk, the uploads and downloads, deletes, conflicts, and why a restored server must look like a new one.
- How a request is served From a socket to a response: threads, the one database lock, the readers, what streams, and what the browser may cache for how long.
- How indexing works What the server works out about each file, when it does it, and why the work is split between the upload and a background worker.
- Search, end to end From an uploaded file to a result on screen: how a document becomes searchable, how the browser gathers what it needs without fetching everything, and why the search runs there.
- How the browser paces its work Opening a notebook: what the browser fetches, what it draws, what it keeps and for how long, and how it stays quick on a phone against a slow server.
- How sign-in and trust work Why a password is kept in a recoverable form and how it is protected anyway, what a session is, how an admin proves it is still them, and why every byte from a tablet is treated as hostile.
- How the app fits a phone, and works offline Why layout is decided by the room there is rather than the device, how a viewer's bar folds, and what the installed app keeps when there is no network.