Developer docs

Documented against main @ bbedf98 (0.8.9-dev, 4 November 2026) · latest release v0.8.8

Contribute

Contribution workflow

From picking an issue to a reviewed pull request, following the project's CONTRIBUTING.md.

Source on GitHub
On this page

This page summarises CONTRIBUTING.md. When in doubt, that file wins.

1. Pick something#

  • Bug fixes: comment on the issue, or open a bug report with steps to reproduce.
  • Features, larger refactors, dependency or architecture changes: open an issue first so maintainers and contributors can agree on scope.
  • New integrations (another wallet, protocol or network backend): talk to us in Telegram first. These are trust and maintenance decisions.
  • Looking for a start? Open for contribution lists issues that are well scoped and close to the developer APIs.

Comment on the issue you take, so nobody duplicates the work. Draft pull requests are welcome for early feedback; maintainers decide whether and when a contribution fits the roadmap.

2. Branch and change#

  • Branch from an up-to-date main.
  • Match the naming and organisation of nearby code, and keep the change focused: unrelated cleanup makes review harder.
  • Read the architecture boundaries before changing process responsibilities or IPC.
  • Do not add or upgrade dependencies without maintainer approval. They affect the attack surface, native builds, package size and licence obligations.
  • Add or update tests for behaviour changes and regressions. Never commit secrets, keys, tokens, seed phrases or unredacted personal data.

3. Commit#

Use Conventional Commit subjects:

<type>(<scope>): <imperative summary>

Allowed types: feat, fix, docs, test, refactor, chore, build, ci, perf, revert. Explain why in the body when the change is not trivial.

Changelog fragments#

A user-visible change adds one file, changelog.d/<section>--<slug>.md, instead of editing CHANGELOG.md. <section> is added, changed, deprecated, removed, fixed or security; the slug can be the issue number, e.g. fixed--280-settings-deeplink.md. The body is the entry as it should read, as bullets, ending in a link to the issue. Developer-only fixes, in-release polish, test-only and internal work need no fragment. Details: changelog.d/README.md.

4. Check#

Before you open the pull request:

npm run lint
npm test                       # or the tests next to the files you changed
npx prettier --check <files you changed>
git diff --check

Run the relevant Playwright or live suite when the change affects UI flows, protocols or nodes; see Setup. The CI matrix runs more native and integration checks. If you could not run one, say so in the pull request instead of ticking it.

5. Open the pull request#

The pull request template asks for:

  • what changed, why, and what users or developers will notice;
  • the related issue (Closes #123);
  • whether a changelog fragment is included;
  • the checks you actually ran;
  • for anything under src/renderer/: before and after screenshots in both themes, following ui-consistency.md.

Stay available for review questions and follow-up changes.

AI-assisted contributions#

AI help is allowed, but a human stays accountable. Review and understand everything you submit, verify generated claims and tests, and disclose material AI assistance in the pull request. Unreviewed automated submissions may be closed.

Licence#

Freedom Browser is licensed under the Mozilla Public License 2.0. Contributions are made under MPL-2.0 unless agreed otherwise. Only submit work you have the right to contribute.