Development Process

Development process

OpenNote is built one tested feature at a time. Every change, from a typo fix to a new feature, takes the same path: branch, pull request, automated checks, review, merge. The full rules are in the development plan and CONTRIBUTING.md.

Phases

The work is split into phases. Each phase adds a small set of features and ends with an exit gate: tests and measurements that must pass before the next phase starts. Short experiments (spikes) come first, so risky choices are proven before much code depends on them.

Unfinished features stay behind feature flags. The main branch must always build, pass every test, and run without crashing. A feature leaves its flag only after it meets the definition of done.

Branches

Branch	Purpose
main	Always builds and passes every test. Phases merge into it.
phase-N	One branch for each phase, such as phase-2. It merges into main with a merge commit when the phase meets its exit gate.
Short-lived branches	Your own change. Branch off the current phase branch, and merge back within a few days.

A fix that isn't part of any phase, such as a typo or an urgent bug, branches off main and targets main. Large phases can be split into work packages on their own branches, which merge into the phase branch. If you can't push to the repository, fork it and open the pull request from the fork.

Pull requests

A good pull request:

• Makes one change that a reviewer can read in one sitting, ideally under 400 changed lines.
• Explains what changed and why, and links the issue it closes.
• Includes screenshots for visual changes, in both the light and dark themes.
• Passes every CI check and has at least one approving review.

Reviewers check behavior, tests, and readability as well as style. Each commit makes one logical change, with an imperative subject line under about 72 characters.

Continuous integration

Every pull request runs on Windows, and on Ubuntu for the checks that don't need Windows:

1. CHECKS on the changed files.
2. Format, lint, and type checks for TypeScript and Rust.
3. Unit, component, and other tests.
4. A check that the design tokens are current, and a debug build of the app on Windows.

A pull request can merge only when all of them pass and one reviewer approves. As phases add tests, CI also runs the end-to-end smoke set and quick performance tests on the built app.

Every night, CI is planned to build main and run the full end-to-end set, fuzzing, soak, crash-safety, and full performance tests. A failure opens an issue automatically.

Merging

• Phase branches merge into main with a merge commit, so each commit stays in the history.
• Pull requests into a phase branch merge once CI passes and a reviewer approves.
• Phase branches pick up new work from main by merging it in.

Decisions and done

• Anything hard to reverse gets an architecture decision record before the code. See Design decisions.
• Every bug gets steps to reproduce, and every TODO in code links to an issue. CHECKS enforces the second rule.
• A feature is done when it works with mouse, keyboard, touch, and pen. It must meet the performance budgets, pass accessibility checks, and use only design tokens. Its data must survive save, crash, undo, and export, and its docs and changelog must be updated. See Testing and quality.

Related pages

• Developer guide
• Releasing