Merge pull request #23 from obilodeau/new-packaging-and-releasing

Packaging improvements and automated releases

Author: obilodeau

.github/release.yml

@@ -0,0 +1,25 @@
+changelog:
+  exclude:
+    labels:
+      - ignore-for-release
+  categories:
+    - title: Breaking changes
+      labels:
+        - breaking
+    - title: Features
+      labels:
+        - feature
+        - enhancement
+    - title: Bug fixes
+      labels:
+        - fix
+        - bug
+    - title: Documentation
+      labels:
+        - docs
+    - title: Dependencies
+      labels:
+        - dependencies
+    - title: Other changes
+      labels:
+        - "*"

.github/workflows/ci.yml

@@ -38,3 +38,30 @@ jobs:
 
       - name: Run CI checks
         run: make ci
+
+  build:
+    name: Packaging dry-run
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # hatch-vcs needs tags/history to compute the version
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: "npm"
+          cache-dependency-path: frontend/package-lock.json
+
+      - name: Build wheel + sdist
+        run: make build
+
+      - name: Verify the SPA shipped in the wheel
+        run: |
+          unzip -l dist/ceopardy-*.whl | grep -q "ceopardy/static/dist/index.html"

.github/workflows/release.yml

@@ -0,0 +1,73 @@
+name: Release
+
+# Triggered by pushing a SemVer tag (vMAJOR.MINOR.PATCH). The strict pattern
+# also rejects accidental tags like `release-1` or `0.6.0` (missing v).
+on:
+  push:
+    tags:
+      - "v[0-9]+.[0-9]+.[0-9]+"
+
+permissions:
+  contents: write # create release + upload assets
+
+jobs:
+  build:
+    name: Build wheel + sdist
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # hatch-vcs needs full history + tags
+
+      - name: Verify tag commit is on main
+        run: |
+          git fetch --no-tags --depth=1 origin main
+          if ! git merge-base --is-ancestor "$GITHUB_SHA" origin/main; then
+            echo "::error::Tag commit $GITHUB_SHA is not on main; refusing to release."
+            exit 1
+          fi
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: "npm"
+          cache-dependency-path: frontend/package-lock.json
+
+      - name: Build frontend bundle
+        run: |
+          npm --prefix frontend ci
+          npm --prefix frontend run build
+
+      - name: Build sdist + wheel
+        run: |
+          pip install build
+          python -m build
+
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  release:
+    name: Publish GitHub Release
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Create release
+        uses: softprops/action-gh-release@v2
+        with:
+          files: dist/*
+          generate_release_notes: true
+          fail_on_unmatched_files: true

.gitignore

@@ -3,6 +3,12 @@ __pycache__/
 *.pyc
 /.venv/
 
+# packaging
+/build/
+/dist/
+*.egg-info/
+/ceopardy/_version.py
+
 # IDE files
 /.idea/
 /.vscode/
@@ -12,17 +18,17 @@ __pycache__/
 /frontend/node_modules/
 
 # Vite build output
-/static/dist/
-
-# Legacy static/vendor directory (no longer produced, kept for safety)
-/static/vendor/
+/ceopardy/static/dist/
 
 # project files
 ceopardy*db
 ceopardy.log
+/game-media/
+# Operator game content — seeded by `ceopardy init` from package templates.
+/data/
 
 # sound files (not provided)
-/static/sounds/*.mp3
-/static/sounds/*.wav
+/ceopardy/static/sounds/*.mp3
+/ceopardy/static/sounds/*.wav
 # these are creative commons sounds
-!/static/sounds/buzzer*.wav
+!/ceopardy/static/sounds/buzzer*.wav

Makefile

@@ -2,7 +2,7 @@
 # the user has activated it (or has direnv loaded). `make venv` creates it.
 export PATH := $(CURDIR)/.venv/bin:$(PATH)
 
-.PHONY: ci lint format format-check test install-dev run venv
+.PHONY: ci lint format format-check test install-dev run venv init build
 
 # Run all CI checks — called by GitHub Actions.
 ci: lint format-check frontend-lint test
@@ -36,6 +36,19 @@ venv:
 install-dev:
 	pip install -r requirements.txt -r requirements-dev.txt
 
+# Seed CWD with example data/ and game-media/. Same as `ceopardy init`,
+# but works without an editable install (dev workflow uses python run.py).
+init:
+	python -m ceopardy init
+
+# Build sdist + wheel (the same path the release workflow takes). Requires
+# the frontend bundle to be present: rebuilds it first.
+build:
+	npm --prefix frontend ci
+	npm --prefix frontend run build
+	pip install build
+	python -m build
+
 # ── Run dev servers (Flask + Vite) in one terminal ──────────────────────────
 
 # Reinstalls when package.json is newer than the install marker.

README.adoc README.mdREADME.adoc renamed to README.md

@@ -1,56 +1,60 @@
-= Ceopardy
+# Ceopardy
 
 The Hacker Jeopardy Game Board we use at NorthSec.
 
-== Screenshots
+## Screenshots
 
 This is what the crowd sees:
 
-image::docs/images/viewer-board.png[The Viewer Interface Displaying the Game Board]
+![The Viewer Interface Displaying the Game Board](docs/images/viewer-board.png)
 
 When a clue is displayed:
 
-image::docs/images/viewer-clue.png[The Viewer Interface Displaying a Clue]
+![The Viewer Interface Displaying a Clue](docs/images/viewer-clue.png)
 
 This is the host interface, how you control the game:
 
-image::docs/images/host.png[The Host Interface]
+![The Host Interface](docs/images/host.png)
 
 Note that there are two drawers that can be opened by clicking on the brown
 arrows at the top and at the bottom of the screen. The top drawer contains
 the functions to change team names. The bottom drawer provides functions to
 display a custom message on the board or to pause a game.
 
 
-== Architecture
+## Architecture
 
 Starting with v0.5, Ceopardy is split in two parts:
 
-* A Python/Flask back-end that exposes a small REST API (`/api/v1/...`) and
+- A Python/Flask back-end that exposes a small REST API (`/api/v1/...`) and
   broadcasts state changes over a single Socket.IO namespace (`/game`).
-* A Vite + Vue 3 front-end (in `frontend/`) that powers the crowd-facing
+- A Vite + Vue 3 front-end (in `frontend/`) that powers the crowd-facing
   viewer, the host UI, and the start screen.
 
 
-== First time deployment
+## First time deployment
 
 You need Python, pip, virtualenv and Node.js (LTS). The tl;dr:
 
     make venv
     source .venv/bin/activate    # bash/zsh
     source .venv/bin/activate.fish    # fish
+    make init                    # seed data/ and game-media/ from templates
     npm install --prefix frontend
     npm run build --prefix frontend
     python run.py
 
 `make venv` creates `.venv/` and installs both runtime and dev requirements.
+`make init` is a one-time step that copies starter `data/1st.round` and
+`data/Questions.cp` into the repo and creates `game-media/`. Edit those files
+to set up your game.
 
-=== Optional: direnv
+### Optional: direnv
 
-If you use https://direnv.net/[direnv], the repo ships an `.envrc` that puts
+If you use [direnv](https://direnv.net/), the repo ships an `.envrc` that puts
 `.venv/bin` on your `PATH` automatically when you `cd` into the directory —
 works in bash, zsh, and fish. Install direnv (see
-https://direnv.net/docs/installation.html[upstream docs] for shell hook setup),
+[upstream docs](https://direnv.net/docs/installation.html) for shell hook setup),
 then from the repo root:
 
     make venv        # create the venv first; direnv won't do this for you
@@ -59,8 +63,8 @@ then from the repo root:
 After that, entering the directory activates the venv and leaving deactivates
 it — no manual `source` needed.
 
-Then open http://127.0.0.1:5000/host[the host view] to set up the game.
-http://127.0.0.1:5000/[The players' view] (also known as the viewer) can be
+Then open [the host view](http://127.0.0.1:5000/host) to set up the game.
+[The players' view](http://127.0.0.1:5000/) (also known as the viewer) can be
 opened at any time.
 
 `python run.py` runs the built-in dev server (debug + reloader). For
@@ -74,7 +78,7 @@ Put nginx (or similar) in front for TLS and to expose it on the network — the
 app itself binds to localhost because the host interface has no auth.
 
 
-== Development
+## Development
 
 Run Flask and Vite side by side. Vite hot-reloads the UI and proxies
 `/api` and `/socket.io` to Flask.
@@ -88,26 +92,32 @@ Run Flask and Vite side by side. Vite hot-reloads the UI and proxies
 Then open http://localhost:5173/.
 
 
-== Setup
+## Install as a CLI (pipx)
 
-=== Display
+Once published, Ceopardy can be installed as a stand-alone command:
 
-You need at least 2 outputs: one for the game host for control and one for the
-public.
+    pipx install ceopardy
+    mkdir my-game && cd my-game
+    ceopardy init        # scaffolds data/ and game-media/ in CWD
+    # edit data/Questions.cp and data/1st.round
+    ceopardy             # or `ceopardy serve` — starts the server
 
-At NorthSec 2017, we used 3 outputs because we didn't have the proper gear to
-duplicate the public output for a stage monitor. There is a script in
-`helpers/` that will set 3 outputs using `xrandr`. It didn't work with a GUI
-tool when we tried at that time.
+`ceopardy init` never overwrites existing files; it's safe to re-run. The
+server, the SQLite database, and the question files all resolve relative to
+the directory you run `ceopardy` from, so keep one directory per game.
 
-== Prepare a game
+
+## Prepare a game
 
 Game data goes in `data/`. There you should add round files (create a `.round`
 file) and questions in `Questions.cp`. The format is pretty self explanatory.
-Check `data/` for an example.
-
-NOTE: In order to avoid dataloss due to a crash, Ceopardy is backed by a
-database where transactions are pushed when the hosts submit the points. This
-has the flipside requiring games to be finalized before a new one can be
-started. Make sure that you always push the "Game over" button before
-reloading to start a new game.
+Run `ceopardy init` (or `make init` from the repo) to get a working starter
+set; `data/1st.round` and `data/Questions.cp` are the minimal example.
+User-supplied media referenced by questions (e.g. `[img:photo.png]`) goes in
+`game-media/` next to `data/`.
+
+> **Note:** In order to avoid dataloss due to a crash, Ceopardy is backed by a
+> database where transactions are pushed when the hosts submit the points. This
+> has the flipside requiring games to be finalized before a new one can be
+> started. Make sure that you always push the "Game over" button before
+> reloading to start a new game.