340 people got here
the same way you will.
Most of them started with a parser for a file format we didn't support, or a documentation fix. Both are real contributions and both get your name in the release notes.
Open good first issues
Median time to first review
Of external PRs get merged
Of the codebase came from contributors
Every good first issue names a file.
"Good first issue" usually means "we couldn't be bothered to scope this". Here it means a maintainer wrote down where to start, what done looks like, and agreed in advance to review it.
Parser for .org files
Emacs org-mode. Start in quire/parsers/markdown.py . The heading logic transfers almost directly.
Unit tests for the numeric entailment rules
"About 340" vs "340" vs "341". The rules are in quire/verify/numeric.py and are under-tested.
quire index progress bar is wrong on resume
Counts from zero instead of from the resume point. quire/cli/progress.py, roughly ten lines.
Document the trace format
It's stable and undocumented. Worst combination. Read quire/trace.py and write it down.
Windows path handling in exclude globs
Backslash separators don't match. Someone with a Windows machine would close this in an afternoon.
Comment before you start and a maintainer will assign it, so two people don't build the same thing. If nobody replies in 48 hours, start anyway and say so.
What we actually check.
- 1 — Does it have a test? One is enough. Not a suite, not fixtures, just the smallest thing that fails if the logic breaks.
- 2 — Does it move a benchmark? Anything touching retrieval or verification runs against
bench/. Regressions are discussed, not auto-rejected. - 3 — Does it add a dependency? If yes, argue for it. The whole install is currently under 40MB and we'd like to keep that.
- 4 — Is it the smallest version? A narrow fix merges today. A refactor of the same area takes three weeks of discussion.
We squash and we credit
Your commits get squashed but your name stays on the commit and goes in the release notes. No CLA to sign. You keep your copyright and licence the contribution under Apache-2.0 by opening the PR.
$ git clone https://github.com/getquire/quire
$ cd quire
$ uv sync --all-extras
$ uv run pytest # 4s, no network
$ uv run quire --help
# before you open the PR
$ uv run ruff check --fix
$ uv run pytest -q
$ uv run quire bench --quick # 90s, retrieval onlyThings that won't get merged
- Telemetry, analytics, or any phone-home, opt-in included
- A hosted-service integration that becomes a soft dependency
- Broad refactors without a bug or benchmark behind them
- New config keys where an existing one would do
- Anything that makes the default path require a network call
Said up front so you don't spend a weekend on a "no". If you disagree with one of these, the Discussions tab is the place. Two of them exist because someone argued well.
Code is maybe half of it.
Answer questions
Most Discord and Discussions answers come from non-maintainers. This is the single most useful unpaid thing anyone does here.
Write a recipe
A config, a command and a paragraph on what broke first. Recipes get more traffic than the docs homepage.
Report a real bug well
A minimal corpus that reproduces it is worth more than a patch. Several fixes came from a good issue and no code at all.
Translate the docs
Four languages so far, all community-maintained. We won't machine-translate. A wrong translation is worse than none.
Break the refusal logic
Find a question where it invents something. Confirmed cases go straight into the benchmark with your name on them.
Test on your platform
Windows and BSD coverage is thin. Running the suite and filing what fails is a genuine contribution.
Short version: be decent, and we'll act if you aren't.
We use Contributor Covenant 2.1. Reports go to conduct@quire.dev, which reaches two maintainers and one person outside the project.
- Reports acknowledged within 48 hours
- The reporter is told what happened, not just that it was "handled"
- Enforcement actions are published in aggregate each year, without names
- Maintainers are not exempt, and one has been asked to step back
On tone in reviews
Reviews should be blunt about code and gentle about people. "This adds a network call to the default path, which we don't do" is fine. "Did you read the contributing guide?" is not, even when the answer is obviously no.
If a maintainer gets this wrong, say so in the thread. It has happened and the correction was public.
Pick one and comment on it.
Median time to first review is 19 hours. If yours sits longer than three days, ping the thread. That's a failure on our side, not rudeness on yours.