Package for public GitHub release
CI / Python checks (pull_request) Has been cancelled
CI / Docker build (pull_request) Has been cancelled

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>
This commit is contained in:
root
2026-06-10 10:13:42 -07:00
parent 2551f8748d
commit ebe4e34047
11 changed files with 313 additions and 161 deletions
+59
View File
@@ -0,0 +1,59 @@
# 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.93.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.93.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).