Contributing

Bug reports, feature requests, documentation, code - all welcome. This page is the short version. The repository’s CONTRIBUTING.md is the long one.

Ways to contribute

Report a bug.
Suggest a feature.
Fix or improve documentation.
Contribute screenshots that match the current UI.
Contribute code.
Help by testing changes.

Report a bug or suggest a feature

Open an issue on GitHub with the right template. Search first - someone may have got there already. For a bug: version, browser, OS, connection mode, the exact steps, and what you expected instead. Troubleshooting lists the rest.

Set up the project

git clone https://github.com/x-rous/actual-bench.git
cd actual-bench
npm install
npm run dev

Use Node.js 22.23.1. Testing HTTP API Server mode properly needs a running actual-http-api - point it at a test budget, not your own.

Branch and PR model

Work on short-lived branches that target main:

Type	Branch prefix
Feature	`feat/*`
Bug fix	`fix/*`
Refactor	`refactor/*`
Docs	`docs/*`

Every pull request targets main. Keep one focused on one thing. Title it the way a user would describe it, and attach screenshots for anything visual. Ships a feature? Update FEATURES.md. Changes what a user sees? Update these docs in the same PR.

Documentation contributions

The docs are their own Astro Starlight project, under docs-site/:

cd docs-site
npm install
npm run dev      # http://localhost:4321/actual-bench
npm run build

When writing docs:

The running app is the source of truth. Use its exact labels, not approximations of them.
Start with one plain sentence that says what the feature does and when to use it.
State requirements and budget impact before the instructions. Do not classify read-only tools or exceptions as write models.
Put the shortest useful workflow first. Put options, implementation details, and rationale after it.
Use direct verbs and name the control a reader must select. Do not make readers infer an action from a metaphor, product comparison, or rhetorical question.
Do not remove product, safety, or capability information just to shorten a page. Consolidate duplicated information in the section that owns it, or move it to a clearly linked canonical page before removing the duplicate.
Keep paragraphs focused on one idea. Use a table or list when readers need to compare choices.
One task, one page. A smaller workflow is a section, not a new page.
Put images under docs-site/src/assets/screenshots/ and reference them relatively.
No real secrets, credentials, private hostnames or personal budget data. Ever.
Keep links relative. They follow DOCS_BASE wherever the site is served; a hard-coded /actual-bench/ only works at the default base.

Every page has an Edit link that takes you straight to its source file on GitHub.

Validate before submitting

From the repository root:

npm run lint      # 0 errors
npx tsc --noEmit  # 0 errors
npm test          # passes
npm run build     # succeeds

Documentation-only change? Run the docs build too: npm --prefix docs-site run build. CI checks it on every pull request.

Security issues

Found a vulnerability? Do not put the exploit in a public issue. The repository’s security policy has the private channel.