Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
59 lines (43 loc) · 2.18 KB

CONTRIBUTING.md

File metadata and controls

59 lines (43 loc) · 2.18 KB
Raw

Contributing to ADS-Bit

Thanks for your interest in improving ADS-Bit! Contributions of all kinds — bug reports, features, sprites, themes, docs — are welcome.

Development setup

ADS-Bit is a Python (aiohttp) backend with a vanilla-JavaScript frontend. There is no build step for the frontend.

git clone <your-fork-url>
cd ADS-Bit
pip install -r requirements.txt      # Python 3.9–3.11 recommended (see note below)
cp config.json.example config.json   # optional; the setup wizard runs otherwise
python3 server.py                     # serves on http://localhost:2001

Or with Docker (no local Python needed):

docker compose up -d

Python version note: the netifaces dependency can be hard to build on Python 3.12+. Use Python 3.9–3.11, or just use the Docker image (Python 3.11).

Project layout

  • server.py — aiohttp server: receiver connections, flight state, APIs, auth.
  • ads-bit.js / index.html — Canvas-based retro viewer.
  • admin/ — admin panel, including the in-browser pixel-editor.js.
  • setup/ — first-run setup wizard.
  • images/, backgrounds/ — sprite and theme assets.

Conventions

  • Frontend assets are cache-busted via a ?v=YYYYMMDD[x] query in admin/admin.html. If you change admin.css, admin.js, or pixel-editor.js, bump that token so browsers reload them.
  • The VERSION constant in server.py is the single source of truth; bump it for releases and add a CHANGELOG.md entry.
  • Keep the retro aesthetic (Press Start 2P, blue/gold palette) for UI work.
  • Match the style of surrounding code; no frontend framework or build tooling.

Submitting changes

  1. Fork and create a topic branch (feature/…, fix/…, chore/…).
  2. Make focused commits with clear messages.
  3. Verify locally: the server starts, the page loads, and your change works. For Docker changes, confirm docker build succeeds.
  4. Open a pull request describing what changed and how you tested it.

CI will byte-compile the server, validate config.json.example, and build the Docker image on every PR.

Reporting bugs / requesting features

Use the issue templates. For security issues, see SECURITY.md.