Contributing to Lines
Thanks for helping. This is how changes get into Lines, for people and for coding agents alike: setting up, making a change, and the commits and pull requests main takes.
Setting up
You need Bun 1.4+, Node.js 22+ (Vite, svelte-check and Tauri's CLI run on it), and for the desktop apps Rust and the Tauri prerequisites.
bun install # only package versions at least 10 days old (bunfig.toml)
bun run dev # the web app, at http://localhost:1420
bun run tauri dev # the desktop app
Making a change
-
Branch from main, named for the change:
fix/sync-lost-edit,feat/spreadsheet-sort. -
Make one change. Something users can see updates its docs, the QA checklist and the feature tour in the same change; CLAUDE.md lists which file covers what. Text the app shows is translated; anything people use works by keyboard and screen reader (Accessibility).
-
Check it:
bun run check # types bun run lint # Oxlint bun run test # unit tests (tests/unit/) bun run test:browser # the app in a headless browser (tests/browser/); BROWSER=webkit for WebKit bun run build bun run i18n # every message translatedA change to what Lines does adds or updates a test of it: a unit test for logic that doesn't need a page (colors, files, what a note's text means), a browser test for what needs the app. Browser tests drive the app as built with
--mode test, whose helpers (src/test/harness.ts,window.testing) open notes and reach Settings directly. A change to what people see also takes the QA pictures again (bun run qa-shots, qa/README.md) to look at.And, when they apply:
bun run qa-notesafter changing how Markdown is read (commit the notes it writes),bun site/build.mjsafter changing the docs or the README (it builds the website's pages intodist-site/and fails on a link that leads nowhere;bunx vite preview --outDir dist-siteshows them),bun run benchbefore and after anything that could make Lines slower (Performance), andcargo clippyandcargo testinsrc-tauri/after changing Rust. -
Try it where people will use it. A change to what people see or do is tried in WebKit (Safari, or the Mac app) as well as Chrome, as they differ; say in the pull request where it wasn't tried.
-
Open a pull request (below).
Commits and pull requests
main is protected: every change, a maintainer's too, comes in through a pull request whose checks pass. Pull requests are squash-merged, so a pull request's title becomes its commit on main, and its description the commit's body. Commits within a pull request can be as many as you like; only the title has to follow the convention.
The title
Conventional Commits: type(scope): what changed.
feat(spreadsheets): fill a series by dragging the selection's corner
fix(sync): keep edits made while a pass is running
perf(list): draw only the notes in view
docs: say how releases are made
| Type | For | Makes a release |
|---|---|---|
feat | Something new people can do or see | yes, minor (0.2.0 → 0.3.0) |
fix | Something that didn't work as it should | yes, patch (0.2.0 → 0.2.1) |
perf | The same, faster or lighter | yes, patch |
refactor | Code changed, behaviour not | no |
docs | Documentation only | no |
test | Tests and benchmarks | no |
build | Dependencies, the build, packaging | no |
ci | Workflows | no |
chore | Anything else that isn't the app | no |
revert | Undoing an earlier change (revert: feat(list): …) | as what it undoes |
style | Formatting only | no |
- Scope (optional): the part of Lines it's about, as a folder or doc names it:
editor,list,notes,sync,spreadsheets,latex,pdf,settings,plugins,themes,i18n,a11y,native(the Rust side),bench,release,deps. - What changed: plain words, as someone using Lines would put it, starting in lower case, no full stop, the whole title within 100 characters. The title says what; the description says why.
- Breaking changes: anything that makes people or plugins do something (notes, sync or the plugin API changing in a way older versions can't read):
!after the type or scope (feat(sync)!: …), and a paragraph in the description startingBREAKING CHANGE:that says what to do. Before 1.0 it makes a minor release.
The conventions check fails on a title that doesn't follow this; bun scripts/release.mjs check-title "…" checks one locally.
The description
The pull request template asks for it: what changed and why, how it was checked (what was run, and tried where), and the checklist. Link the issue it closes (Closes #123). Screenshots or a recording for anything that looks or moves differently.
Checks
Every pull request runs .github/workflows/checks.yml, and has to pass:
conventions: the titlecla: everyone who contributed to it has agreed to the contributor agreementweb: types, lint, unit tests, translations, QA notes up to date, the website's links, the buildbrowsers: the browser tests, in Chromium and WebKitrust (macos-latest),rust (windows-latest),rust (ubuntu-22.04): Clippy (warnings fail) and the tests, for each desktop system
Every night, .github/workflows/flakes.yml runs the browser tests three times in each browser, on a runner of its own and on one kept busy, and notes any failure in the issue "Flaky browser tests". A test that fails only now and then is a bug, in the test or in Lines: find why and fix that, rather than retry it, wait longer or skip it. The workflow can be run by hand on a branch, as many times as it takes to show a fix works.
Coding agents
The same rules, and:
- Never push to main; open a pull request. Don't merge one unless asked to.
- The person you work for agrees to the contributor agreement; it covers what you contribute for them.
- One change per pull request, from a branch of its own.
- Say what you verified and how, and what you couldn't (the Mac app, a phone, a real sync provider). Don't describe a check you didn't run.
- Name yourself: a
Co-authored-by:trailer for the agent in commits you write, and a line at the end of the description saying which agent made it. - Don't bump versions or edit
CHANGELOG.md: the release pull request does both.
Contributor agreement
Before your first pull request is merged, you agree to Lines' contributor agreement: a bot asks on the pull request, and you reply with the sentence it gives. Once covers everything you contribute afterwards.
You keep the copyright in what you contribute. You give Lines' maintainer a broad license to it, and every version of Lines that includes it stays open source. Lines asks because it's under the AGPL: without the agreement, every contributor's code could only be passed on under the AGPL's terms, and Apple's App Store terms (iPhone, iPad, the Mac App Store) add restrictions the AGPL doesn't allow, so Lines couldn't be published there, nor its license ever changed.
Contributing for an employer: make sure you may, as the agreement asks you to confirm. A coding agent's pull request is covered by the person it works for, who agrees once on their own account.
Releases
Merging into main never releases by itself. A bot keeps a pull request titled chore(release): v… open, with the next version worked out from the merged titles above and the changelog written from them; merging it tags the release and builds the apps. Releasing has the details.
Dependencies
Only versions published at least 10 days ago are installed (bunfig.toml), so a compromised release has time to be caught; Dependabot proposes updates weekly under the same rule. A new dependency needs a reason in its pull request, a license that fits the AGPL, and bun run notices (the third-party licenses Lines shows in About).