root
ebe4e34047
Add open-source scaffolding and CI; remove Claude-specific dev notes from the published tree. - Remove CLAUDE.md from tracking (kept locally, now git-ignored). - CHANGELOG.md (Keep a Changelog; v1.0 → v1.1.1). - SECURITY.md (private vuln reporting + operator guidance). - CONTRIBUTING.md (dev setup, conventions, PR flow). - .github/: bug + feature issue templates, PR template. - .github/workflows/ci.yml: byte-compile, validate example config, docker build. - .github/workflows/release.yml: on a version tag, publish a multi-arch (amd64 + arm64) image to GHCR. - README: license/release/CI badges, prebuilt-image (GHCR) run instructions, and a corrected Python-version note (3.9–3.11; netifaces caveat). Badges and image names use an `OWNER` placeholder to replace with the GitHub namespace after the repo is created. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
60 lines
2.2 KiB
Markdown
60 lines
2.2 KiB
Markdown
# 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.
|
||
|
||
```bash
|
||
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):
|
||
|
||
```bash
|
||
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](SECURITY.md).
|