From 53c13268eebc5d6953ee567aff4304c5f728123f Mon Sep 17 00:00:00 2001 From: ann0see <20726856+ann0see@users.noreply.github.com> Date: Tue, 21 Jul 2026 23:17:14 +0200 Subject: [PATCH 1/4] Add agent instructions for Jamulus and update CONTRIBUTING.md CONTRIBUTING.md: point agent-assisted contributors at AGENTS.md. Co-Authored-By: jrd Co-Authored-By: Peter L Jones Co-Authored-By: Claude Fable 5 --- AGENTS.md | 78 +++++++++++++++++++++++++++++++++++++++++++++++++ CONTRIBUTING.md | 2 ++ 2 files changed, 80 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000000..4978a8da50 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,78 @@ +# Jamulus — Agent Instructions + +Real-time networked music jamming app. Qt/C++ qmake project. Client and server share same codebase. Entry point: `src/main.cpp`. Configure `CONFIG` flags in `Jamulus.pro`. + +**Make the smallest possible change. One logical change per PR. Never mix refactoring with fixes/features.** + +Priority order: Stability > Low latency / real-time safety > Backwards compatibility > Maintainability > New features. This order resolves conflicts only — new features are welcome. + +--- + +## Build + +Linux: `qmake && make` (use `qmake-qt5` on Fedora). Headless server: `qmake "CONFIG+=headless serveronly" && make`. First run: `git submodule update --init` (oboe for Android). See `COMPILING.md` for the full per-platform table. + +macOS (xcode spec) use: `qmake QMAKE_APPLE_DEVICE_ARCHS=arm64 QT_ARCH=arm64 -spec macx-xcode Jamulus.pro` +(Use `x86_64` on Intel Macs; `macx-clang` to build with `make`). Then `xcodebuild build`, +and `macdeployqt ./Release/Jamulus.app` (or `./Debug/Jamulus.app`) to make it runnable. + +No test suite: run a headless server, connect a client to `127.0.0.1`, exercise the change, and state in the PR what you tested. + +## Never Do + +**`Never Do` rules are absolute** + +- Block or slow: audio callbacks, socket handling, server mixing timers (stalls = audible dropouts). Preallocate buffers; keep real-time paths lock-free. +- Allocate excessive memory, do file I/O, or log excessively in real-time paths (blocks the audio thread). +- Trust any value received from a remote client — validate size and bounds on all network input (malformed input crashes). +- Edit generated files: `moc_*.cpp`, `ui_*.h`, `qrc_*.cpp`, `*.qm` — regenerate, don't hand-edit. +- Edit or reformat third-party code in `libs/` (e.g. opus, oboe, NSIS). +- Edit `ChangeLog` directly — use a `CHANGELOG:` line in the PR instead. + +## Always + +- Attach test evidence (logs/output) to the PR — never just assert something works. +- Say so if you did not run or verify something. + +## Ask first + +- Architecture changes (e.g. networking/protocol, threading, build system) — open an issue to discuss (see `CONTRIBUTING.md`). + +## Qt / portability + +- Minimum Qt: **5.12.2**. Qt 6 recommended (not for iOS, see below). Guard newer APIs with `#if QT_VERSION >= QT_VERSION_CHECK(...)`. +- C++11 (C++17 on Android for Oboe). +- iOS builds require Qt 5.15 or later (Qt 6 buggy on iOS). +- Preserve platform support. Don't break Android/iOS builds. +- Supported desktop: Windows 10+, macOS 10.10+, Ubuntu 20.04+/Debian 11+. + +## Style (C / C++ / Obj-C++) + +```bash +make clang_format # run before committing (target exists only after qmake generated Makefile) +``` + +- **CI uses clang-format** (check `.github/workflows/coding-style-check.yml` for version). +- CI runs **shellcheck + shfmt** on `.sh` files; **pylint** (config: `.pylintrc`) on `.py` files in `tools/`. +- All new contributions: AGPL 3.0+ license header. Pre-3.12.1dev code: GPL 3.0+ (see `CONTRIBUTING.md`). +- Use `tr ( "Hello %1" ).arg ( name )` for user-facing strings — never string concatenation. + +## JSON-RPC + +- If change RPC methods are changed, regenerate `docs/JSON-RPC.md` with `tools/generate_json_rpc_docs.py` (CI fails otherwise). +- Requires `--jsonrpcport` + `--jsonrpcsecretfile` at runtime. Binds to localhost by default. + +## PR expectations + +- One logical change per PR — no unrelated cleanup or reformatting of untouched code. Discuss features in an issue before implementing. See `CONTRIBUTING.md`. +- Branch `autobuild.*` triggers CI builds on your fork. +- Follow `.github/pull_request_template.md`. Include `CHANGELOG:` line with changelog description. For new deps/build changes, add `AUTOBUILD: Please build all targets`. +- Builds? Tested? Smallest change possible? Self reviewed against "Priority order" above? +- Disclose AI-generated text in PRs/issues — never in code comments. + +## Read when relevant + +- `CONTRIBUTING.md` — process, style, licensing +- `COMPILING.md` — full build per platform, CONFIG flags table +- `docs/JAMULUS_PROTOCOL.md` — network protocol, packet IDs, ack rules +- `SECURITY.md` — security reporting diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9b666045f6..6645bf58e2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -7,6 +7,8 @@ We’d really appreciate your support! Please ensure that you understand the fol - Otherwise, please [post on the GitHub Discussions](https://github.com/jamulussoftware/jamulus/discussions) and say that you are planning to do some coding and explain why. Then we can discuss the specification. - Please begin coding only after we have agreed on a specification to avoid putting a lot of effort into something that may not be accepted later. +If you work with an AI coding agent, [AGENTS.md](AGENTS.md) is its entry point into this repository. Everything in this document applies to agent-assisted contributions without exception: you remain the author, and you are expected to understand and stand behind every line you submit. + ## Jamulus project/source code general principles From f223eba34a5f8cb0ab44a87044ab6306ba63ceb1 Mon Sep 17 00:00:00 2001 From: ann0see <20726856+ann0see@users.noreply.github.com> Date: Mon, 10 Aug 2026 10:22:39 +0200 Subject: [PATCH 2/4] Fix typo Co-authored-by: John Dempsey <1750243+mcfnord@users.noreply.github.com> --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 4978a8da50..06cc268e01 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -59,7 +59,7 @@ make clang_format # run before committing (target exists only after qmake gene ## JSON-RPC -- If change RPC methods are changed, regenerate `docs/JSON-RPC.md` with `tools/generate_json_rpc_docs.py` (CI fails otherwise). +- If RPC methods are changed, regenerate `docs/JSON-RPC.md` with `tools/generate_json_rpc_docs.py` (CI fails otherwise). - Requires `--jsonrpcport` + `--jsonrpcsecretfile` at runtime. Binds to localhost by default. ## PR expectations From 7ca77c0842655bb19faa9703d6528542ebc3d177 Mon Sep 17 00:00:00 2001 From: ann0see <20726856+ann0see@users.noreply.github.com> Date: Mon, 10 Aug 2026 10:23:09 +0200 Subject: [PATCH 3/4] Make autobuild trigger more explicit Co-authored-by: John Dempsey <1750243+mcfnord@users.noreply.github.com> --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 06cc268e01..57bf6a58f8 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -65,7 +65,7 @@ make clang_format # run before committing (target exists only after qmake gene ## PR expectations - One logical change per PR — no unrelated cleanup or reformatting of untouched code. Discuss features in an issue before implementing. See `CONTRIBUTING.md`. -- Branch `autobuild.*` triggers CI builds on your fork. +- Branch names starting with `autobuild` trigger CI builds on your fork. - Follow `.github/pull_request_template.md`. Include `CHANGELOG:` line with changelog description. For new deps/build changes, add `AUTOBUILD: Please build all targets`. - Builds? Tested? Smallest change possible? Self reviewed against "Priority order" above? - Disclose AI-generated text in PRs/issues — never in code comments. From 4256065c88d892be53f8351e33e6ccd2c0c49b52 Mon Sep 17 00:00:00 2001 From: ann0see <20726856+ann0see@users.noreply.github.com> Date: Mon, 10 Aug 2026 10:23:34 +0200 Subject: [PATCH 4/4] Add folder names Co-authored-by: John Dempsey <1750243+mcfnord@users.noreply.github.com> --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 57bf6a58f8..5d48fb8dde 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -22,7 +22,7 @@ No test suite: run a headless server, connect a client to `127.0.0.1`, exercise **`Never Do` rules are absolute** -- Block or slow: audio callbacks, socket handling, server mixing timers (stalls = audible dropouts). Preallocate buffers; keep real-time paths lock-free. +- Block or slow: audio callbacks (`src/sound/`), socket handling (`src/socket.cpp`), server mixing timer (`src/server.cpp`) — stalls = audible dropouts. Preallocate buffers; keep real-time paths lock-free. - Allocate excessive memory, do file I/O, or log excessively in real-time paths (blocks the audio thread). - Trust any value received from a remote client — validate size and bounds on all network input (malformed input crashes). - Edit generated files: `moc_*.cpp`, `ui_*.h`, `qrc_*.cpp`, `*.qm` — regenerate, don't hand-edit.