The README had grown to about 500 lines. It now holds the intro, a quick start and an index, and the rest lives in docs/. - docs: add docs/README.md as the index of all pages - docs: move install, configuration, demo, providers, OpenSubsonic, API, security and backups, web app, Android app and development/releases to their own pages, text unchanged - docs: split the feature list into five pages under docs/features/ - docs: rewrite internal anchors as links between the new pages - chore: add docs to .dockerignore, next to README.md
4.7 KiB
Development and releases
Development
go vet ./...
go test -race ./...
The default test run needs no network and uses SQLite only. To run the same storage tests against PostgreSQL as well, start a throwaway server and point the tests at it:
docker run -d --rm --name sonda-test-pg -e POSTGRES_PASSWORD=sonda -e POSTGRES_DB=sonda -p 127.0.0.1:55432:5432 postgres:17-alpine
SONDA_TEST_POSTGRES_DSN='postgres://postgres:sonda@127.0.0.1:55432/sonda?sslmode=disable' go test -race ./...
docker rm -f sonda-test-pg
Tests that read real audio need ffmpeg and are skipped when it is missing.
Layout:
cmd/sondad/ the server: wiring, config, logging, shutdown
internal/api/http/ the REST API (thin handlers) and the docs routes
internal/api/openapi/ the OpenAPI spec, embedded in the binary
internal/auth/ users, roles, passwords, access and refresh tokens
internal/catalog/ browsing and searching artists, albums, tracks
internal/library/ libraries, the scanner, the event hub, the tag reader
internal/about/ descriptions of artists, from Wikipedia through MusicBrainz and Wikidata
internal/discovery/ similar artists: what the providers said, kept and refreshed
internal/providers/ external providers: settings, the outbound HTTP client, the clients of the providers
internal/naming/ names for lists of songs: a local namer, and Claude when it is on
internal/listening/ listen events
internal/taste/ what the listener likes, learned from the listening history
internal/discover/ the score of an artist you may like, and the suggestions
internal/feedback/ the wishlist and the artists a user is not interested in
internal/playlists/ the playlists of each user
internal/mixes/ the mixes made for a listener, by genre and by listening
internal/smart/ smart playlists: rules that are worked out into songs
internal/images/ covers made from the pictures in the user's own files
internal/usersettings/ the settings that belong to one user
internal/storage/ SQLite and PostgreSQL through bun, the repositories
internal/streaming/ opening a track's file safely
migrations/ SQL migrations, one folder per database
web/ the web client (React, Vite, shadcn/ui)
Dockerfile, compose.yaml the image of sondad, and an example for Docker Compose
The API description is internal/api/openapi/openapi.yaml, written by hand and embedded in the binary. Two tests keep it in step with the code: one fails when a route and the spec disagree in either direction, and a contract test sends real requests through every operation and validates each response (status, headers, JSON body) against the spec. Adding or changing an endpoint therefore means updating the spec in the same change. Response objects are closed (additionalProperties: false), so a field added in the code and forgotten in the spec fails the build.
Migrations are plain SQL files in migrations/sqlite and migrations/postgres. They must describe the same schema, and a test checks that both folders hold the same files. Add a new numbered file to both whenever the schema changes.
Releases
Every merge into main can make a release, by itself (.forgejo/workflows/release.yml, semantic-release). The next version comes from the messages of the commits since the last one, written as Conventional Commits:
| Commit | Release |
|---|---|
fix: ..., perf: ... |
patch (0.2.0 to 0.2.1) |
feat: ... |
minor (0.2.0 to 0.3.0) |
feat!: ..., or BREAKING CHANGE: in the body |
major (0.2.0 to 1.0.0) |
docs:, test:, chore:, ci:, style: |
none by themselves |
A release adds its entry to CHANGELOG.md, tags the commit (v0.3.0), makes the release on the forge, and the image is built from the tag and pushed to git.kmalloc.org/squid/sonda as 0.3.0, 0.3 and latest. The version is inside the binary: GET /version and the User-Agent of the providers say it (a build that no release made says dev). The commit that writes CHANGELOG.md says [skip ci]. The image is made for amd64 and for arm64, and each tag points at both. The runner has no Docker and cannot emulate ARM, so the images are built with kaniko: the Go program is compiled for ARM with no emulation, the last stage of the Dockerfile runs no command, and a last job (with crane) says the architecture of each image and joins them. The workflow needs the secret FORGEJO_TOKEN: a token of the owner with the scopes write:repository and write:package.