diff --git a/AGENTS.md b/AGENTS.md index ad6ce4f..c0fb776 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -31,8 +31,34 @@ synced `.venv/bin/python` explicitly. ```bash uv sync # resync the environment (do this first) +git submodule update --init # contrib/homebrew, the Homebrew tap uv run pytest # full test suite uvx ruff check . # lint (ruff is not a project dependency) uv run beefy-player --list # station ids for the current catalogue uv run python tools/ansi_art.py ... # regenerate a provider's header art ``` + +`uvx ruff check .` is the enforced lint and must pass. `ruff format` is **not** +enforced: the tree is not format-clean (54 files would change), so never run a +repo-wide reformat as a side effect of an unrelated change. + +## Packaging + +`contrib/` holds the two distribution channels, and they work differently: + +- **`contrib/aur/`** — plain tracked files (`PKGBUILD`, `.SRCINFO`), edited + here. The package is not published in the AUR (sign-ups are closed), so + `makepkg -si` from a checkout is the only route. `_commit` pins the archive + the package builds from and must move with each release. +- **`contrib/homebrew/`** — a **git submodule** of the tap at + `https://tildeforge.dev/beefcarver/homebrew`, not a copy. Formula changes + belong in the tap repository; commit them there and bump the gitlink here. + Never add loose files under that path. The formula still carries a + placeholder `sha256`, so it only installs with `--HEAD`. + +## Releases + +`.forgejo/workflows/release.yml` fires on a `v*` tag: it asserts that the tag, +the `pyproject.toml` version and `beefy_player.__version__` all agree, then +publishes release notes. It does **not** touch packaging, so bump +`contrib/aur/PKGBUILD` (and its `.SRCINFO`) and the tap's formula by hand. diff --git a/README.md b/README.md index b02d497..1b29ccd 100644 --- a/README.md +++ b/README.md @@ -102,22 +102,46 @@ too. From a checkout, `nix develop` gives you `uv`, `ruff` and the audio tools for the usual `uv sync` / `uv run pytest` workflow; `nix build` builds and tests the package. +### Homebrew + +A tap lives at **[tildeforge.dev/beefcarver/homebrew](https://tildeforge.dev/beefcarver/homebrew)**. +Homebrew's one-argument `brew tap` assumes GitHub, so point it at the tap URL +and trust the formula explicitly: + +```bash +brew tap beefcarver/homebrew https://tildeforge.dev/beefcarver/homebrew.git +brew trust --formula beefcarver/homebrew/beefy-player +brew install beefcarver/homebrew/beefy-player +``` + +`brew update` refreshes the tap and `brew upgrade` picks up new versions like +any other formula. The formula builds from source, with `numpy`, `pillow`, +`mpv` and `ffmpeg` pulled in as Homebrew dependencies. + +No release is tagged yet, so the formula still carries a placeholder checksum +and cannot install from a tarball. Until the first `v*` tag is published, use +`brew install --HEAD beefcarver/homebrew/beefy-player`. + +The tap is a git submodule at `contrib/homebrew`, so the formula and its +maintenance notes live in the tap repository itself; after cloning this one, +run `git submodule update --init` to check it out. + ### Arch Linux -The `aur/PKGBUILD` here is AUR-ready, but the package is not published in the -AUR: the AUR has closed new sign-ups, so there is no account to push it to. -Build and install it from a checkout instead: +The `contrib/aur/PKGBUILD` here is AUR-ready, but the package is not published +in the AUR: the AUR has closed new sign-ups, so there is no account to push it +to. Build and install it from a checkout instead: ```bash git clone https://tildeforge.dev/beefcarver/beefy-player -cd beefy-player/aur +cd beefy-player/contrib/aur makepkg -si # needs base-devel; builds, runs the test suite, installs ``` Once the AUR accepts new accounts again, the package can be published and `paru -S beefy-player` / `yay -S beefy-player` will work; until then `makepkg` -is the only route. The `aur/PKGBUILD` is tracked and kept in sync with every -release either way. +is the only route. The `contrib/aur/PKGBUILD` is tracked and kept in sync with +every release either way. The Python side is pulled in automatically. For audio, the output-synced spectrum and image passthrough through tmux, install the optional tools too: @@ -259,15 +283,32 @@ These stay in the usual XDG locations on every platform, macOS included; ## Development ```bash -uv sync # create the environment -uv run pytest # test suite -uvx ruff check . # lint +uv sync # create the environment +git submodule update --init # contrib/homebrew, the Homebrew tap +uv run pytest # test suite +uvx ruff check . # lint ``` Each catalogue is a self-contained provider module under -`beefy_player/providers/`; `base.py` documents the interface. `tools/ansi_art.py` -converts a PNG logo into half-block ANSI art. On NixOS, `nix develop` (or the -older `shell.nix`) provides the same `uv sync` / `uv run` workflow. +`beefy_player/providers/`; `base.py` documents the interface. Every catalogue's +header is a wordmark from the shared half-block font, and the header paints it +with the active palette gradient (`hero_gradient`, on by default) so all +thirteen follow the terminal's colours. `tools/ansi_art.py` converts a PNG logo +into half-block ANSI art that carries colours of its own; a provider using that +art must set `hero_gradient = False`, because the header would otherwise +repaint it with the gradient. + +`uvx ruff check .` is the enforced lint. The tree is not `ruff format`-clean (54 +files would change), so do not reformat it wholesale. + +Pushes run the test suite (`.forgejo/workflows/tests.yml`); a `v*` tag runs +`release.yml`, which checks that the tag, `pyproject.toml` and +`beefy_player.__version__` agree and then publishes the release notes. It does +not touch packaging, so `contrib/aur/PKGBUILD` and the tap's formula are bumped +by hand for each release. + +On NixOS, `nix develop` (or the older `shell.nix`) provides the same `uv sync` / +`uv run` workflow. ## Licence