Roadmap: what's open, how hard it is, and how to claim it

[LeyckerS]

This is the landing page for anyone who wants to contribute. Everything open is listed below, ranked by size, with the two things that actually matter up front: how hard it is, and whether you need Windows.

MoonDownloader runs on Windows, but almost none of the open work requires it. Documentation, CI, tests and dependency work all run on Linux and macOS, and the test suite stubs Chrome and the network at the moon_extract boundary so it runs anywhere. Exactly one open issue needs a Windows machine, and it says so.

Most of the bugs below were found by using the program, not by reading it. Several come with measurements from real runs in the issue itself, so you can check the fix against a number instead of a feeling.

Last checked against the repository: 12 August 2026.

Never contributed to open source before?

Three issues are reserved for people who have never had a pull request merged anywhere. All three are done entirely in the browser — no install, no command line, nothing to run.

Issue	What you change
#79	One line of a comment in ruff.toml that describes its own effect incorrectly
#80	Delete one unused constant from moon_engine.py — taken by @mazi-eth
#93	One line so a CI workflow watches its own file on pull requests, as it already does on push

The work is deliberately small. The point is to get you through fork → edit → pull request once, with every step written out. If you get stuck halfway, say so on the issue — that is what it is there for.

If you have contributed before, please leave these three and take something below.

Free right now

Nothing here is claimed. No Windows machine needed unless the row says so.

Issue	What it is	Size	Needs Windows
#83	Extractors sits under "COMMON — BOTH METHODS" but datanodes is hard-capped at 8 lanes. Measured: fuckingfast keeps ~40 of 48 download slots busy, datanodes keeps ~4	~20 lines	Helpful
#164	ruff.toml and pytest.ini are not in any workflow's paths filter — so the two files that decide what CI enforces are the two files that never trigger it. A pull request touching only one of them gets no checks at all	Small	No
#57	Engine.snapshot() has no unit tests, and it is the contract both front-ends read ~12 times a second. Held for @XEDAB for a couple of days — see the issue — then open to everyone	~40 lines	No
#64	A square backdrop appears behind the progress rings during a run	GUI/CSS	Yes

#83 is the most valuable one free, and it is the only open bug found by measuring rather than reading: the two providers get the same "streams" setting in the interface while one of them cannot use more than 8 lanes, so the number on screen is not the number in effect.

Genuinely running low on free work — if nothing here fits, say so on #39 and I will write something that does. That is not a formality; the bottleneck in this project is available issues, not people.

Claimed, in progress

Listed so nobody duplicates the work. If one has gone quiet for five days it goes back to the free table above, and returning is always welcome.

Issue	Who	State
#97	@breezeFur	PR #154 open — CLI progress driven by Engine.snapshot()
#85	@8nt0n	The ETA clamping to exactly 2 hours and presenting it as real
#117	@tomatotomata	The COMPLETED counter reporting failures as completions
#84	@happykawayigt	MiB/MB unit mismatch, all labelled "MB/s"

Recently shipped

Some context on what the work here looks like when it lands:

• bug: Stop leaves the UI on STOPPING until every in-flight download finishes on its own #65 — Stop now interrupts transfers already in flight (@Allen58562, Stop in-flight downloads when stopping engine #149). The engine keeps each active download's kill event in a registry and signals it with loop.call_soon_threadsafe; a user stop is recorded as stopped so the retry path cannot re-queue it and undo the stop.
• a full disk is treated as an ordinary per-file error: the run continues and burns bandwidth it cannot write #116 — a full disk stops the run instead of burning bandwidth it cannot write (@shard872, fix: stop downloads when destination is full (#116) #150). ENOSPC detected by errno, a shared abort both front-ends observe, .tmp files kept for resume, and the folder named on screen.
• enhancement: give moon_cli.py meaningful exit codes for scripting #32 — the CLI reports the run's outcome in its exit code (@AdvaitVarhade, feat(cli): structured exit codes for moon_cli.py #153). 0 all succeeded, 1 some failed, 3 all failed, 2 a pre-flight problem — so a script can finally tell the difference.
• ci: ruff runs three times per pull request, once per Python version, checking the same thing #81 — ruff runs once per pull request instead of five times (@nightcityblade, ci: run ruff once outside syntax matrix #158), with the version pin kept.
• test_no_chrome.py reports success when the run produced no files, so the ok assertion cannot fail #155 — an assertion four tests had been running for weeks could never fail (@XEDAB, fix: remove the never-failing ok assertion in test_no_chrome.py (#155) #157). Found while reviewing someone else's pull request.
• THEME color block in moon_engine.py: zero references, tests pass without it — but why is it here? #145 — the generated-era THEME palette is gone (@AashishGupta2007, removed the dead theme block in moon_engine.py #159), after checking all fifteen hex values against web/styles.css.
• conftest stubs download_file on moon_cli only — the engine keeps the real one, and nothing currently notices #160 — the test suite could have made real network requests (@XEDAB, fix: apply the download_file stub to moon_engine too (#160) #162). One stub sat outside the loop that patches both front-ends, so the engine held the real downloader.
• silence the aiohttp BasicAuth deprecation warning in the test run (the call itself has to stay) #151 — the aiohttp.BasicAuth deprecation no longer clutters the test output (@Divesh-Kshirsagar, test: suppress aiohttp BasicAuth deprecation warning #161), matched by exact message so a genuine future deprecation still surfaces.
• fix: update proxy status handling (#115) #132 — the proxy chip tells the truth before a run starts (@8nt0n), distinguishing "no file" from "file with nothing usable in it".
• engine/cli: collect and report browser worker failures #143 — both worker gathers collect their failures (@PomPomSaturin) instead of aborting on the first one, and name the worker that failed.
• V4 repaired both providers after they changed how they hand out links.

How to claim one

Comment on the issue saying you are taking it. You will be assigned, usually within a few hours. (If the assignee field stays empty, that is GitHub, not a rejection: it only accepts assignees who have commented on the issue itself. Your comment is the claim either way, and I record it in the table below.) You do not need to ask permission first, and you do not need to have a plan — saying "taking this, not sure yet how" is fine and gets you the same answer.

A claim holds for five days, counted from whichever of us spoke last — if you are waiting on me, the clock is not running against you. After that the issue goes back to the free table so it is not parked indefinitely — no blame attached, and you are welcome to pick it up again.

Two things worth knowing before you start:

1. Read the function, not the description. Issue bodies here are written by the maintainer and have been wrong before — docs(cli): fix stale --proxies row and document the actual warning behavior #63 was merged partly because it corrected a mistake in the issue that opened it. If the code disagrees with the issue, the code wins and I would rather hear it.
2. Keep the diff to the issue. Reformatting, renaming and "while I was in there" edits are the most common reason a pull request needs a second round, even when each change is harmless on its own.

CONTRIBUTING.md has the verification commands. Everything else — architecture, style, the rules that are not preferences — is in there too, and nothing in this issue repeats it.