Contributing

Contributing

Where is open source (Apache 2.0) and built with its community. Thanks for being here!

Ways to help, no code needed

• Test it. Install Where on your computer, especially Mac, Linux and ARM, and report what breaks.
• Improve this wiki. Anyone with a GitHub account can edit it. Fix a confusing step, add a screenshot, add a FAQ.
• Share ideas with the Feature request template.
• Design. Mockups for new pages, icons, onboarding.
• Spread the word. Tell people who drown in folders and tabs.

Ways to help with code

Good places to start:

• Issues labelled good first issue and help wanted
• A Firefox version of the browser extension
• Search inside documents (text, Markdown, PDF) in where_indexer
• A remove folder button in Settings → Indexed folders
• Tests: more Rust tests, and Flutter widget tests
• Speed: a benchmark with 100,000 items

For anything bigger than a small fix, open an issue first so we can agree on the approach before you spend time on it.

How to send a change

1. Fork the repo and clone your fork.
2. Build it: see Building from Source.
3. Make a branch: feat/<short-name> or fix/<short-name>.
4. Make your change, and keep the checks green:

   cargo fmt --all
   cargo clippy --all-targets -- -D warnings
   cargo test --all
   cd apps/where_flutter && flutter analyze && flutter test

5. Add a line to CHANGELOG.md under Unreleased if users will notice it.
6. Open a pull request and fill in the template.

A maintainer reviews it, usually within a few days. Small, focused pull requests get merged fastest.

Rules every change must follow

Where must never delete or change the user's files, send messages, upload data by default, or run commands without confirmation. New permissions (a folder, a browser, an integration) must be explicit and visible in Settings. See the principles.

Keep private things out of the repo

Only source code and docs belong in Git. Before every push:

git status
git diff --cached --stat

Never commit databases (*.db), exports, logs, build output, .env files, keys or passwords. .gitignore blocks the common ones. If something slipped in:

git rm -r --cached .
git add .
git commit -m "Stop tracking files that aren't source code"

Use GitHub's private email for commits: GitHub → Settings → Emails → Keep my email addresses private.

Licensing

By opening a pull request you agree your contribution is licensed under the Apache License 2.0, the same as the rest of Where. Your copyright stays yours. Only submit code you wrote, or code whose license allows it (MIT, BSD, Apache 2.0…), and say where copied code came from. Please avoid GPL-only dependencies.

Be kind

Everyone was new once. See the Code of Conduct and how decisions are made in GOVERNANCE.md.