Repository navigation
Description
👋 New here? Welcome! This is the place to start contributing to Gulliver. Every issue below says where to start and when it's done, and is marked free, claimed or done.
This week shaw778, mayankdhingra02, ariktadas144, Doomguy-BFG9000, 17302513901yh-lang, Muhtasim-Munif-Fahim, Abhishekpandey123-git, abu-tahir-0, hamid-digitalmarketer, yinbowen-dc, draarivpatel-ui, MM071022, HarshRajSinghania, dianatofficial, tyza66, amritkang165, rohangoud17, Hayabusa-YL, arpanjot-coding, Ipsita-Mondal-30, AzalHoseinian, IG-ABHINAV, Mr45401 and others landed PRs or opened them in Gulliver. Yours could be next.
Update 2026-11-11: #97 is done: PR #99 by @yinbowen-dc was merged, thank you. #80 is done too: PR #105 by @shaw778 was merged, thank you. #93 (PR #101) and #98 (PR #100) have approved PRs that now need the latest
mainmerged in (the CHANGELOG line conflicts; keep both lines). #108 (PR #110, @draarivpatel-ui), #112 (PR #115, @dianatofficial), #111 (PR #117, @tyza66), #113 (PR #114, @HarshRajSinghania), #119 (PR #121, @dianatofficial) and #129 (PR #137, @amritkang165) each have a PR in review, and #134 has a PR (#136, @HarshRajSinghania). #106 has PR #138 (@rohangoud17), #128 is claimed by @amritkang165 with PR #139, #126 is claimed by @amritkang165 with PR #144, #107 is claimed by @rohangoud17 (PR #140 is also open for it), and #118 and #130 have PRs (#141 and #142, @arpanjot-coding). #120 is claimed by @umang-jpg. Free right now, good first issues: #122, #123, #124 and #127. Free right now, a step up: #109 (someone has offered; a short plan was asked for first), #125, #131, #132, #133 and #135. When an issue is free, comment on it first, then start: the first claim goes forward, and a second PR for the same issue only costs both of us time.
Update 2026-11-13: #122 is claimed by @shaw778 (PR #147). #111 (PR #117, @tyza66) is approved and waits for CI. #123 has a PR (#146, @deshmukh-viraj). Free right now, good first issues: #124 and #127.
Update 2026-11-13 (later): ten new issues, all free. Good first issues: #150, #151, #152, #153, #154, #155 and #159 (a translation, no code needed). A step up: #156, #157 and #158. #124 now has a PR (#149, @HarshRajSinghania), so the free good first issues are #127 and #150-#155, plus #159.
Update 2026-11-15: done and merged: #108 (PR #110, @draarivpatel-ui), #111 (PR #117, @tyza66), #129 (PR #137, @amritkang165) and #156 (PR #164, @Ipsita-Mondal-30). Thank you! #157 has PR #165 (@Ipsita-Mondal-30), #127 has PR #162 (@IG-ABHINAV), #106 has PR #138 (@rohangoud17) and #119 has PR #121 (@dianatofficial); these four and #123 (PR #146) need the latestmainmerged in (the CHANGELOG line conflicts; keep both lines).
Update 2026-11-15 (later): done and merged: #119 (PR #121, @dianatofficial) and #150 (PR #163, @AzalHoseinian, a first PR). Thank you! #153 is claimed by @Mr45401 (PR #167, which needsmainmerged in); #152 is claimed by @dianatofficial (PR #168). A person can hold three open assigned issues at a time, so a claim is assigned as soon as one of someone's PRs is merged. Free right now: #151, #154, #155 and #159 (good first issues, #151 and #155 already have a PR open that waits for a free slot), and #125, #131, #132, #133, #135 and #158 (a step up). The PRs for #123, #127, #106, #157, #107, #124, #128, #126, #118, #130 and #98 need the latestmainmerged in (the CHANGELOG line conflicts; keep all lines).
Update 2026-11-15 (CHANGELOG): contributors no longer editCHANGELOG.md; the maintainer adds the entry, with credit, when a PR is merged. If your PR only conflicts inCHANGELOG.md, drop your CHANGELOG change (or mergemainand take main's version of that file) and push; the rest of the PR stays as it is.
Update 2026-11-15 (afternoon): done and merged: #151 (PR #170) and #152 (PR #168), both by @dianatofficial, and #127 (PR #162, @IG-ABHINAV, a first PR here). Thank you! #154 (PR #166) and #155 (PR #172) are now assigned to @dianatofficial. #112 (PR #115) needsmainmerged in once more (tests/test_cli_and_mcp.py). Free right now: #159 (good first issue, no code needed), and #125, #131, #132, #133, #135 and #158 (a step up; #158 has a PR from someone at the three-issue limit).
Update 2026-11-15 (evening): #155 (PR #172) is approved, and #154 (PR #166) is reviewed with one small test to add. Both only need their CHANGELOG change dropped before they can merge. #118 stays with the earlier PR #141 (@arpanjot-coding), which is approved and needsmainmerged in (src/gulliver/fixer.py). Free right now: #159 (good first issue, no code needed), and #125, #131, #132, #133, #135 and #158 (a step up; #158 has a PR from someone at the three-issue limit).
Update 2026-11-15 (night): #131 is claimed by @AzalHoseinian. #154 (PR #166) has its CHANGELOG change dropped and only needs the one test line; #153 (PR #167, @Mr45401) is reviewed and needs its CHANGELOG change dropped plus a small fix for lower-case zone names. Free right now: #159 (good first issue, no code needed), and #125, #132, #133, #135 and #158 (a step up; #158 has a PR from someone at the three-issue limit).
Update 2026-11-15 (late): done and merged: #155 (PR #172), #154 (PR #166) and #112 (PR #115), all by @dianatofficial, and #153 (PR #167, @Mr45401, a first PR here). Thank you! #158 is now assigned to @dianatofficial (PR #174), and #133 is claimed by @shaw778 (PR #179). Free right now: #159 (good first issue, no code needed), and #125, #132 and #135 (a step up).
Update 2026-11-16: done and merged: #158 (PR #174, @dianatofficial). Thank you! New good first issue: #191, three GV005 fix-advice cases that still suggest a rewrite that changes results (@dianatofficial has first claim). Free right now: #159 and #191 (good first issues; #191 goes to @dianatofficial first if they want it).
Update 2026-11-17: done and merged: #125 (PR #186, @Ipsita-Mondal-30) and #132 (PR #183, @tyza66). Thank you! #106 (PR #138, @rohangoud17) only needs its CHANGELOG change dropped. Free right now: #159 and #191 (good first issues; #191 goes to @dianatofficial first if they want it).
Update 2026-11-17 (later): done and merged: #191 (PR #193, @dianatofficial). Thank you! Free right now: #159 (good first issue, no code needed).
How it works
- Pick a free issue and comment on it ("I'd like to take this"). You'll be assigned, so nobody else works on the same thing. Please wait for a claimed issue to free up rather than opening a second PR for it.
- Read CONTRIBUTING.md. Setup: Python 3.10+,
pip install -e ".[dev]", thenpytestandruff check .. - Open a pull request. Do not edit
CHANGELOG.mdin your pull request; the maintainer adds the entry, with credit to you, when it is merged. This keeps pull requests from conflicting with each other. CI runs on Windows, macOS and Linux. Small PRs are reviewed quickly. - When it's merged, you're thanked by name in the CHANGELOG or release notes.
Easy: good first issues
- GV005: three fix-advice cases still suggest a rewrite that changes results #191 Lint GV005: three fix-advice cases (COALESCE with a non-literal default or wrapped column, Postgres integer division, TRIM) still suggest a rewrite that changes results (done in PR fix(lint): avoid rewrite false positives in GV005 fix advice (#191) #193, thanks @dianatofficial)
- Lint GV003: a NATURAL JOIN is reported as a cartesian product (error), so preflight and run block a normal query #150 Lint GV003: a
NATURAL JOINis reported as a cartesian product (error), sopreflightandrunblock a normal query (done in PR fix(lint): do not flag NATURAL JOIN as a cartesian product (GV003) #163, thanks @AzalHoseinian) - rehearse:
--fractions abcshows a raw Python error and a negative--seedfails with a parser error about "[removed by gulliver]" #151rehearse:--fractions abcshows a raw Python error and a negative--seedfails with a parser error about "[removed by gulliver]" (done in PR fix(rehearse): validate --fractions format and refuse negative --seed (#151) #170, thanks @dianatofficial) - diff: an unknown column in
--columnsreaches the engine and comes back as a raw "Binder Error", while an unknown--keygets a clear message #152diff: an unknown column in--columnscomes back as a raw engine "Binder Error", while an unknown--keygets a clear message (done in PR fix(diff): refuse unknown columns before running diff queries (#152) #168, thanks @dianatofficial) - fix --verify: an unknown
--timezoneis not refused; the rewrite is reported as "exactly the same rows" with exit code 0 and nothing was tested #153fix --verify: an unknown--timezoneis not refused; the rewrite is reported as "the same rows" with exit code 0 and nothing was tested (done in PR fix(verify): refuse unknown --timezone before rewriting or testing #167, thanks @Mr45401) - Result guard: a connection URL with a password in it (postgresql://user:password@host/db) is returned unmasked #154 Result guard: a connection URL with a password in it (
postgresql://user:password@host/db) is returned unmasked (done in PR fix(guard): mask connection URLs containing embedded passwords (#154) #166, thanks @dianatofficial) - receipt --list: when nothing matches it prints an empty line and "Use a receipt_id ...", also for a mistyped
--status#155receipt --list: when nothing matches it prints an empty line and "Use a receipt_id ...", also for a mistyped--status(done in PR fix(receipt): provide actionable messages and status hints on empty list (#155) #172, thanks @dianatofficial) - Docs: translate the README quick start into your language #159 Docs: translate the README quick start into your language (free, no code needed; any number of languages, say which one you take)
- check: refuse a negative --min-rows and a negative, NaN or infinite --max-change #106
check: refuse a negative--min-rowsand a negative, NaN or infinite--max-change(claimed by @rohangoud17, PR fix: refuse invalid --min-rows and --max-change in check #138) - spend: a very large --days crashes with a Python traceback instead of an error message #107
spend --dayswith a very large number crashes withOverflowError(claimed by @rohangoud17; PR fix(spend): reject a --days window wider than a year #140 is also open) - Period values such as
prune --older-than 99999999999dandcheck --fresh ts=99999999999dcrash with a traceback #108parse_periodoverflow (prune --older-than,check --fresh,incremental) crashes with a traceback (done in PR fix(period): refuse out-of-range periods without a traceback #110, thanks @draarivpatel-ui) - fix --verify: --cases 0 quietly becomes 200 and a negative --cases runs one case and reports ok #111
fix --verify:--cases 0quietly becomes 200 and a negative--casesruns one case and reports ok (done in PR fix(verify): refuse --cases below one instead of silently changing it (#111) #117, thanks @tyza66) - demo: --events with a negative number creates a demo that reports "events: -5" #112
demo --events -5creates a demo that reports "events: -5" (done in PR fix(demo): validate --events bounds before creating demo database (#112) #115, thanks @dianatofficial) - mcp --http: a --port outside 0-65535 crashes with an OverflowError traceback #113
mcp --http --port 70000crashes with anOverflowErrortraceback (claimed by @HarshRajSinghania, PR fix: reject MCP --port values outside 0-65535 with a clean error #114) - fix --mode all: --limit -5 writes "LIMIT -5" into the SQL and --limit 0 quietly becomes the default #118
fix --mode all --limit -5writesLIMIT -5into the SQL and--limit 0quietly becomes the default (PR fix: reject nonpositive limits in all-mode rewrites #141 by @arpanjot-coding, approved; needsmainmerged in) - run --max-rows: a negative number quietly returns an empty preview and reports ok #119
run --max-rows -5quietly returns an empty preview and reports ok (done in PR fix(run): refuse negative --max-rows before querying (#119) #121, thanks @dianatofficial) - check: --not-null "" passes with nothing checked, and an empty column name in --unique or --accepted reaches the engine #120
check --not-null ""passes with nothing checked, and an empty column name in--uniqueor--acceptedreaches the engine (claimed by @umang-jpg) - impact, lineage and drift --models: a folder with no .sql files reports "Nothing downstream uses it" instead of saying no models were found #122
impact,lineageanddrift --models: a folder with no.sqlfiles says "Nothing downstream uses it" instead of saying no models were found (done in PR fix(models): refuse folder with no .sql files with status error (closes #122) #147, thanks @shaw778) - check and incremental: a malformed --fresh, --range, --accepted or --period value ends with "Fix the problem above and try again." and the message does not show the format #123
checkandincremental: a malformed--fresh,--range,--acceptedor--periodvalue ends with the generic "Fix the problem above" and does not show the format (PR fix(cli): name the flag in malformed check option errors #146 by @deshmukh-viraj) - Docs: demo --events/--overwrite, incremental --no-savings and mcp --host/--port are missing from the README CLI reference and have no --help text #124 Docs:
demo --events/--overwrite,incremental --no-savingsandmcp --host/--portare missing from the README CLI reference and have no--helptext (PR docs: document missing CLI options and add --help text (#124) #149 by @HarshRajSinghania) - gulliver.toml: a section with the wrong type (budget = 3, lint = 5, [connections] x = 1) crashes with a Python traceback #126
gulliver.toml: a section with the wrong type (budget = 3,lint = 5,[connections] x = 1) crashes with a Python traceback (claimed by @amritkang165, PR Report invalid config section types without tracebacks (#126) #144) - An unknown default_connection in gulliver.toml and an unknown -c name on
statusare quietly replaced by another connection #127 An unknowndefault_connectioningulliver.tomland an unknown-cname onstatusare quietly replaced by another connection (done in PR fix: refuse unknown default_connection and -c NAME on status (#127) #162, thanks @IG-ABHINAV) - SQL syntax errors show sqlglot's internal Token repr, and the next_step talks about statement types instead of the syntax error #128 SQL syntax errors show sqlglot's internal Token repr, and the
next_steptalks about statement types instead of the syntax error (claimed by @amritkang165, PR Make SQL syntax errors readable and actionable (#128) #139) - Lint rule:
col = NULLandcol <> NULLare never true, so the query scans the table and returns nothing #129 New lint rule:col = NULLandcol <> NULLare never true, so the query scans the table and returns nothing (done in PR Add a lint warning for comparisons with NULL (#129) #137, thanks @amritkang165) - check:
gulliver check TABLEwith no check options says "All checks passed." although nothing was checked #130check TABLEwith no check options says "All checks passed." although nothing was checked (PR fix: distinguish empty data-quality checks from validation #142 by @arpanjot-coding) - Docs: a step-by-step tutorial on the bundled demo database (inspect, lint, fix, rehearse, run, receipt) #134 Docs: a step-by-step tutorial on the bundled demo database (PR docs: add step-by-step tutorial on the demo database #136 by @HarshRajSinghania)
- spend, calibration and top: refuse --days and --limit below 1 instead of quietly changing them #92 Refuse
--daysbelow 1 and a negative--limitinstead of quietly changing them (done, thanks @hamid-digitalmarketer) - gulliver receipt --list: filter by --action and --connection #93
receipt --list:--actionand--connectionfilters, plus the missing README line (PR Filter receipt listings by action and connection #101 by @yinbowen-dc) - inspect: refuse --limit and --scan outside the range MCP already enforces, instead of quietly clamping #97
inspect: refuse--limitand--scanoutside the range MCP already enforces (done, thanks @yinbowen-dc) - incremental --lookback and prune --keep-last: refuse negative numbers #98
incremental --lookbackandprune --keep-last: refuse negative numbers (PR Reject negative lookback and receipt retention counts #100 by @yinbowen-dc) - Result guard: detect UK National Insurance numbers by value #21 Result guard: detect UK National Insurance numbers by value (claimed by @Dodothereal, PR Detect UK National Insurance number formats in text values #65)
- gulliver spend -o PATH and gulliver top -o PATH #19 gulliver spend -o PATH and gulliver top -o PATH (done, thanks @Muhtasim-Munif-Fahim)
- gulliver rules --format markdown|json, and generate the README lint table from it #18 gulliver rules --format markdown|json, and generate the README lint table from it (done, thanks @Muhtasim-Munif-Fahim)
- check --range: refuse NaN, infinite and inverted bounds with a clear message #74 check --range: refuse NaN, infinite and inverted bounds with a clear message (done, thanks @abu-tahir-0)
- check --max-change: -c default and no -c keep separate row-count histories #75 check --max-change: -c default and no -c keep separate row-count histories (done, thanks @abu-tahir-0)
- Budget: refuse fractional values for whole-number limits and true/false for any limit #76 Budget: refuse fractional values for whole-number limits and true/false for any limit (done, thanks @abu-tahir-0)
- gulliver.toml: a typo in a section name such as [budjet] is silently ignored #77 gulliver.toml: a typo in a section name such as [budjet] is silently ignored (done, thanks @abu-tahir-0)
- GV013: also flag LIKE patterns that start with the '_' wildcard #78 GV013: also flag LIKE patterns that start with the '_' wildcard (done, thanks @abu-tahir-0)
- GV002 is skipped when a scalar subquery in the SELECT list aggregates #33 GV002 is skipped when a scalar subquery in the SELECT list aggregates (done, thanks @17302513901yh-lang)
- Lint rule GV018 count-for-existence #31 Lint rule GV018 count-for-existence (done, thanks @17302513901yh-lang)
A step up: intermediate
- Lint:
JOIN u ON 1=1andON t.id = t.idget no finding, so a full cartesian product passes the gate and runs #156 Lint:JOIN u ON 1=1andON t.id = t.idget no finding, so a full cartesian product passes the gate and runs (done in PR fix(lint): report a join condition that does not link the tables as GV003 (#156) #164, thanks @Ipsita-Mondal-30) - incremental: a
--time-columnor--unique-keythat does not exist is accepted, and the generated model uses it (status ok, exit code 0) #157incremental: a--time-columnor--unique-keythat does not exist is accepted, and the generated model uses it (claimed by @Ipsita-Mondal-30, PR fix(incremental): refuse a --time-column or --unique-key that does not exist (#157) #165) - Lint GV005: the fix advice is always the date-range example, also for
UPPER(name) LIKE ...,amount * 1.2 > 100andCOALESCE(status, 'x') = 'x'#158 Lint GV005: the fix advice is always the date-range example, also forUPPER(name) LIKE ...,amount * 1.2 > 100andCOALESCE(...)(done in PR feat(lint): provide tailored fix advice for GV005 (#158) #174, thanks @dianatofficial; follow-up in GV005: three fix-advice cases still suggest a rewrite that changes results #191) - check: a referential-integrity check (--relationship), so orphan rows are found in the same scan #109
check --relationship COL=TABLE.COL: a referential-integrity check inside the same guarded scan (free; an offer is waiting for a short plan) - Lint rule GV019 having-on-group-column: a HAVING condition that only uses GROUP BY columns belongs in WHERE (with a same-rows autofix) #125 Lint rule GV019
having-on-group-column: aHAVINGcondition that only usesGROUP BYcolumns belongs inWHERE, with a same-rows autofix (done in PR feat(lint): GV019 having-on-group-column (#125) #186, thanks @Ipsita-Mondal-30) - Lint rule: function on a join key (ON LOWER(a.id) = LOWER(b.id)) is not flagged, although the same function in WHERE is (GV005) #131 Lint rule: a function on a join key (
ON LOWER(a.id) = LOWER(b.id)) is not flagged, although the same function inWHEREis (claimed by @AzalHoseinian) - check: a null-rate check (--max-null COL=PCT) for columns that may have some NULLs but not too many #132
check --max-null COL=PCT: a null-rate check for columns that may have some NULLs but not too many (done in PR feat(check): --max-null COL=PCT for columns that may be partly empty #183, thanks @tyza66) - lint --format markdown: a findings table for GITHUB_STEP_SUMMARY and PR comments (a new report format) #133
lint --format markdown: a findings table forGITHUB_STEP_SUMMARYand PR comments (claimed by @shaw778, PR feat(lint): add markdown output format for CI job summaries and PR comments (closes #133) #179) - Example: a small dbt-style project with gulliver.toml, a GitHub Actions workflow and a pre-commit config to copy #135 Example: a small dbt-style project with
gulliver.toml, a GitHub Actions workflow and a pre-commit config to copy (docs, free) - Data checks in gulliver.toml: define them once, run them all with
gulliver check --all#80 Data checks in gulliver.toml: define them once, run them all withgulliver check --all(done in PR feat(checks): define checks in gulliver.toml and run with gulliver check --all (closes #80) #105, thanks @shaw778) - gulliver prune: clean up old receipts without breaking
gulliver audit verify#79 gulliver prune: clean up old receipts without breakinggulliver audit verify(done, thanks @shaw778) - gulliver lint --baseline: report only new findings on an existing repo #45 gulliver lint --baseline: report only new findings on an existing repo (done, thanks @ariktadas144)
- gulliver diff: say which columns differ for changed keys #46 gulliver diff: say which columns differ for changed keys (done, thanks @shaw778)
Questions, or an idea of your own? Comment here or open an issue. Every kind of help counts, including docs, translations and bug reports.
If Gulliver is useful to you, a ⭐ on the repo helps other people find it.
Activity
laaielichter commentedon Nov 16, 2026
Update 2026-11-16: merged: #139 (PR #139, @amritkang165, done for #128) and #144 (PR #144, @amritkang165, done for #126). Thank you! Credits for both are in #185. #132 is claimed by @tyza66 (PR #183 is open; it needs the CHANGELOG change dropped before merge). #138 and #161 (both @rohangoud17) need their CHANGELOG change dropped, and #138 also needs two stray lines removed from
tests/test_cli_and_mcp.py. #157 is claimed by @Ipsita-Mondal-30 (PR #165 is still open for it). #135 has a PR open from @yinbowen-dc (#184), so it is no longer free. Free right now: #159 (good first issue, no code needed) and #125 (a step up).Generated by Claude Code