Files
poli0981andClaude Fable 5.2 0e0e442de5 chore: maintenance mode, Qodana analysis; 4.6.1 (#188) [skip-discuss]
The project moves to maintenance mode (stable, feature-complete): docs, templates and badges (EN + VI). Qodana analysis in CI for the TypeScript / JavaScript, Python and Rust projects, with the findings of its first reports fixed. Version 4.6.1.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
2026-11-11 21:44:32 +07:00

13 KiB

Contributing Guidelines

Thanks for even thinking about contributing to this random repo! I'm just an unemployed, introvert Vietnamese dev with mediocre skills and two non-judgmental AI buddies: Grok (xAI) for the late-night brainstorming and Claude Code (Anthropic) for the heavier code/docs work. This list survives on community help, because I'm too lazy to hunt/fix everything alone :D Any contribution (even one game) makes you a legend.

Project Status: Stable, Maintenance Only

Since version 4.6.1 (2026-11-11) the project is stable and in maintenance mode. It is feature-complete: the website, the apps and the data pipeline keep running, and the catalog keeps updating itself.

  • Still done by the Maintainer: security fixes (CVEs and reports made through SECURITY.md), runtime and dependency updates, and repairs when something stops the site or the daily data updates from working.
  • Not done any more: new features, redesigns, refactors.
  • Issues and pull requests are accepted for the data only: adding games (section 1), fixing a game's data or removing a game (sections 2 and 3). Accessibility barriers (section 3) and security reports keep their own channels. Anything else is closed without review; no hard feelings.

How to Contribute (Use the Right Door, I'm Lazy ;D)

Games go through the website; data fixes and removals go through the GitHub issue templates or email. They make my life easier and reduce "wtf" moments.

1. Suggest New Games (Most Welcome!)

  • Go to https://freeitchgames.win/suggest and paste an itch.io game link. One link per submission.
  • Optional: a short note (why it's good, content warnings…), up to 500 characters. Notes are deleted after 180 days. Please don't put personal data in it.
  • A Cloudflare Turnstile check and a rate limit keep bots out; if you get blocked, wait a bit and try again.
  • Only free itch.io games. Paid games are dropped automatically when the game page is scraped.
  • The game must be playable or downloadable on its itch.io page itself (a browser build or an uploaded file). A page that only points to a launcher or a download on another site doesn't qualify, even when that is free: the Disclaimer tells visitors that any download happens on itch.io.
  • Nothing goes live instantly: every suggestion lands in a review queue, where the Maintainer approves or rejects it, by hand or through automatic rules (a suggestion without a warning flag that nobody rejected within about a day may be approved automatically). Approved links are then scraped by the data pipeline and show up on the site after the next deploy.

Got a whole list? The [Add Games (bulk list)] issue template takes up to 15 links at once, and a PR that adds itch.io URLs to scripts/temp_link.json works too (use the [Add Games] PR template). Both go through the same review: the Maintainer checks every link before it is queued, and merging such a PR is the approval. Please don't edit data_game/ by hand: the pipeline owns those files (see section 7).

1b. Other ways games get in

  • The site reads itch.io's public RSS feeds of new and popular free games every 4 hours (one feed per run) and queues what it finds.
  • The site also reads the public itch.io collections the Maintainer follows and queues their new free games directly (one removed before, or with a warning flag, goes to the review queue instead).

The RSS feeds land in the same review queue as the Suggest page. (The Maintainer's browser extension and the old Telegram bot are retired; their repositories, itch-f2p-extension and telegram-scraper-bot, are archived.)

2. Remove Games or Fix Their Data

Game creators especially: if you want your game off the list, or its data corrected, that's always fine.

  • Email takedown@poli0981.dev, or open the "Remove a game" issue template (it also has a section for copyright claims).
  • Include the game URL, who you are (the creator / rights holder, or someone authorized by them) and the reason.
  • The Maintainer removes the record from the catalog (logged with a reason on the public removed-games page) and deletes the resized cover copies the site stores; cached copies expire on their own. Target: within 7 days, urgent legal requests sooner.
  • Heads-up: this is a public git repo, so past versions stay in its history. Rewriting public history is only done in exceptional cases of legal necessity.
  • Wrong safe_virus / nsfw / notes, or other data errors that aren't a removal? Use the [Report a problem] issue template (section 3).

Details live in the Terms of Use and the Disclaimer.

3. Report a Problem (Wrong Data, Something Broke)

  • Open an issue → [Report a problem] template (direct link).
  • It is for data errors (dead link, wrong name, genre, tags, cover, nsfw or safe_virus flag…) and for things that broke (a page or an app that stopped working, the catalog no longer updating). It is not for ideas: see section 4.
  • Details + screenshots + urgency level.
  • Security problems are not for the public tracker. Report them privately: see SECURITY.md.
  • Accessibility barriers (keyboard, screen reader, zoom, contrast, motion…): use the [Accessibility barrier] template (direct link), or email contact@poli0981.dev if you'd rather not use GitHub. What happens next is in ACCESSIBILITY.md.

4. Features and Improvements (Closed)

  • The project is in maintenance mode: feature requests, improvement ideas and code changes are no longer accepted. Such issues and pull requests are closed without review.
  • The code is MIT-licensed: you're welcome to fork it and build your own thing (README → License).

5. Feedback, Questions, Anything Else

  • Use GitHub Discussions, the Discord servers or email (see "Discuss More" below). Roast or praise, my self-loathing can handle it.
  • They are read, but they don't turn into new features (section 4).

6. Dependencies and Security Fixes

  • Dependency updates are handled by Dependabot and the Maintainer's weekly sweep: please don't send version-bump PRs.
  • Found a vulnerability? Report it privately (SECURITY.md); the Maintainer makes the fix.

7. Pull Requests

  • Accepted: a PR that adds itch.io URLs to scripts/temp_link.json (use the [Add Games] PR template). Merging it is the Maintainer's approval.
  • Not accepted: everything else (code, UI, docs, refactors). Fixing or removing a game's data goes through an issue or email (sections 2 and 3), because the pipeline owns data_game/.
  • The rules below still apply to every PR, the Maintainer's own included.

PR rules (the non-negotiable part):

  • CI must pass. Python CI (ruff check + format, vulture, pytest, validate.py) and Webapp CI (Tauri crate/npm version check, type generation check, lint, knip, tests, build, wrangler deploy --dry-run) both run on PRs. Red CI = no merge. SonarQube Cloud also analyses each PR (with test coverage) and reports its quality gate as the "SonarCloud Code Analysis" check, and Qodana (JetBrains) analyses the TypeScript / JavaScript, Python and Rust code. Both skip PRs from forks, which get no repository secrets.
  • PRs are merged with squash (one PR becomes one commit on main) or a merge commit, never by fast-forward, so make the PR title a good commit message (the repo uses the type(scope): summary style, e.g. fix(web): …).
  • Licensing is inbound = outbound. By opening a PR you agree that your contribution is licensed under the same license as the part it changes: MIT for code, CC BY 4.0 for catalog data and documentation (see README → License). Only submit work you have the right to submit.
  • Never commit secrets: no tokens, API keys, .dev.vars / .env files, private keys (such as the GitHub App key) or signing keystores. If you pushed one by accident, report it privately (security@poli0981.dev) and rotate it; deleting the commit is not enough.
  • Don't edit data_game/ by hand. Data changes go through the pipeline (a patch + apply_patch.py, which runs validate.py), so concurrent writers never clobber each other.
  • Don't commit build output or generated files: webapp/dist/, webapp/.wrangler/, webapp/src-tauri/target/, webapp/src-tauri/gen/. (webapp/src-tauri/Cargo.lock is committed; keep it in sync when you change Cargo.toml.)
  • Adding an npm dependency? Also add it to the THIRD_PARTY list in webapp/src/lib/about.ts so the About page credits it.
  • New external link in the app? Use <ExtLink href="…"> from webapp/src/components/ext-link.tsx, not a plain <a href="…" target="_blank">: plain anchors work on the web but silently break in the Tauri apps (and ExtLink tells screen readers the link opens a new tab).
  • Accessibility: UI changes keep working with the keyboard alone and with screen readers, and keep the contrast ratios (npm test checks the colours). The checklist is in ACCESSIBILITY.md → For contributors and in the pull request template.

8. Dev Setup (Summary)

For forks, and for the Maintainer's own maintenance work.

Full instructions (Worker, local D1, secrets, Tauri, Android) are in docs/dev_env.md; the Tauri/Android build notes are in webapp/TAURI.md. The short version:

Python pipeline (Python 3.15, see .github/python-version):

python -m venv .venv
# activate it, then:
pip install -r requirements-dev.txt
pytest                                   # no network needed
ruff check scripts tests webapp/scripts
ruff format scripts tests
python scripts/validate.py               # checks every data file

To try a real scrape locally: add a URL to scripts/temp_link.json, then run python scripts/update_info.py --out patch.json and python scripts/apply_patch.py patch.json (don't commit the result; see the PR rules above).

Webapp + Worker (Node.js 26+, CI uses the version in webapp/.node-version):

cd webapp
npm ci
npm run dev          # Vite on http://localhost:5173
npm run build        # writes to webapp/dist/ (the Worker serves it as its assets)
npx wrangler dev     # second terminal: Worker on :8787; Vite proxies /api and /img to it
npm test             # vitest
npm run lint
npm run knip

Tauri apps (also needs Rust via https://rustup.rs and platform deps):

cd webapp
npm run tauri:dev    # native window pointing at the Vite dev server
npm run tauri:build  # installers in src-tauri/target/release/bundle/

Tips for Smooth Contributing

  • Test locally: run the checks from section 8 before pushing; CI runs the same ones.
  • Keep it clean: only free itch.io games, no paid/demo/malware/duplicates.
  • Be patient: I'm introvert + lazy, replies might be slow.
  • Agreement: all issue templates have a required checkbox. Off-topic/spam/policy violations, and anything outside the maintenance scope above, get ignored/closed without drama :D
  • Be cool: everything here falls under the Code of Conduct.

Discuss More? (If Templates Aren't Enough)

Issues are best for tracking data problems, but if you wanna chit-chat, ask something, or share noob stories, there are GitHub Discussions and actual servers now (introvert god-mode breached):

Chat / community

Social (DMs open, replies slow)

Support the boredom project (totally optional, $50 bank account thanks you)

Grok and Claude Code can't join Discord, but ping me on any channel, I'll try not to ghost.

Big thanks in ACKNOWLEDGEMENTS.md for any help!

Code is MIT, data and docs are CC BY 4.0: go wild, but chill. Questions? Just open a [General] issue :D 🚀