73 lines
3.0 KiB
Markdown
73 lines
3.0 KiB
Markdown
# AGENTS.md
|
|
|
|
Notes for coding agents working in this repository.
|
|
|
|
## Re-sync the uv environment before doing anything
|
|
|
|
The checked-out `.venv` is **not** portable. It is built by `uv sync`, and its
|
|
`python` symlink points at a uv-managed interpreter path belonging to whichever
|
|
machine created it (for example `/home/node/.local/share/uv/python/...`). When
|
|
the repository is re-synced from the host, that interpreter is gone, the
|
|
symlink dangles, and every `.venv/bin/*` command fails with:
|
|
|
|
.venv/bin/python: No such file or directory
|
|
|
|
So always re-sync first — before tests, lint, the app, or any tooling:
|
|
|
|
```bash
|
|
uv sync
|
|
```
|
|
|
|
If it still fails, rebuild the environment once:
|
|
|
|
```bash
|
|
rm -rf .venv && uv sync
|
|
```
|
|
|
|
There is no project Python on `PATH`; use `uv run <command>` or the freshly
|
|
synced `.venv/bin/python` explicitly.
|
|
|
|
## Commands
|
|
|
|
```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
|
|
```
|
|
|
|
`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's Python dependencies are
|
|
vendored as `resource` blocks: Homebrew installs the sdist with `--no-deps`,
|
|
so a dependency that has no block (or whose constraint changed in
|
|
`pyproject.toml`) is simply missing at runtime. Regenerate them in the tap
|
|
with `brew update-python-resources Formula/b/beefy-player.rb`;
|
|
`uv run python bump_packaging.py <version> --check` reports a dependency
|
|
without one.
|
|
|
|
## 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 run
|
|
`uv run python bump_packaging.py <version>` after publishing: it rewrites
|
|
`contrib/aur/PKGBUILD` and regenerates its `.SRCINFO` from it, rewrites the tap
|
|
formula in `contrib/homebrew`, and with `--commit` commits the tap first and
|
|
then this repository. Both channels build the sdist attached to the release,
|
|
so they hash the same asset.
|