From e140acbbb883c40975da8c5dc19db5928d9151a8 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/3] Add agent instructions for Jamulus and update CONTRIBUTING.md CONTRIBUTING.md: point agent-assisted contributors at AGENTS.md. - Contributors remain accountable for every line of AI-generated code. Co-Authored-By: jrd Co-Authored-By: Peter L Jones Co-Authored-By: Claude Fable 5 --- AGENTS.md | 59 +++++++++++++++++++++++++++++++++++++++++++++++++ CONTRIBUTING.md | 2 ++ 2 files changed, 61 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000000..0c6f394c34 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,59 @@ +# Jamulus — Agent Instructions + +Real-time networked music jamming app. Qt/C++. Entry point: `src/main.cpp`. Configure `CONFIG` flags in `Jamulus.pro`. + +## DO NOT edit (generated or third-party) +- `moc_*.cpp`, `ui_*.h`, `qrc_*.cpp` are generated at build time (moc/uic/rcc) — never hand-edit. +- `*.qm` under `.qm/` are committed compiled translations — never hand-edit (regenerate from the `.ts` sources). +- `libs/` is third-party (opus, oboe, NSIS). `libs/oboe` is a git submodule — run + `git submodule update --init` if it is empty. Do not apply clang format on any of those files. + +## Build / verify +- Linux desktop: `qmake && make` (use `qmake-qt5` on Fedora). +- Headless server: `qmake "CONFIG+=headless serveronly" && make`. +- macOS: `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` to make it runnable. More infos: COMPILING.md. + +## Style (C / C++ / Obj-C++) +- Before committing `.cpp/.h/.mm` or after `qmake Jamulus.pro`, run `make clang_format`. +- **CI uses clang-format** (see `.github/workflows/coding-style-check.yml` + `clangFormatVersion` for version). +- Rules: tabs→4 spaces, braces on their own line, space inside `()` and around + `if/for/while` conditions, column limit 150, left pointer alignment (`int* p`). +- New files must carry an AGPL 3.0 (or later) license header. +- Existing pre-3.12.1 code being amended should already carry combined AGPL 3.0 and GPL 2.0 (or later) license blocks. + code is GPL 2.0+. + +## Tests +- No automated test suite. + +## Translations +- Use `tr ( "Hello %1" ).arg ( name )` — never concatenate translatable strings with `+`. +- Per-language `.ts` files live in `src/translation/`. + +## JSON-RPC +- If you change RPC methods, regenerate `docs/JSON-RPC.md` with + `tools/generate_json_rpc_docs.py` (CI fails otherwise — `check-json-rpcs-docs.yml`). + +## Other tooling +- `.sh` files: lint with `shellcheck --shell=bash` and `shfmt -d`. +- Python (under `tools/`): max line length 99, run `pylint` (< 3.0) with `.pylintrc`. +- ChangeLog: put `CHANGELOG: ` in the PR description. Do **not** edit + the `ChangeLog` file (causes conflicts). + +## Version / portability constraints + +- Minimum Qt: **5.12**. Guard newer APIs with `#if QT_VERSION >= QT_VERSION_CHECK(...)`. +- Preserve C++11/17 and Android/iOS compatibility. + +## PR expectations +- Branch named `autobuild/` triggers CI builds on your fork. +- Include `CHANGELOG:` line with a brief changelog discription and, for new deps/build changes, the + `AUTOBUILD: Please build all targets` tag. + +## Before finishing + +- Do not modify generated or third-party files. +- Format code. +- Ensure changes build for the affected target(s). 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 282f29a086d9df97df409f160fe52f8220616e21 Mon Sep 17 00:00:00 2001 From: ann0see <20726856+ann0see@users.noreply.github.com> Date: Thu, 23 Jul 2026 16:17:10 +0200 Subject: [PATCH 2/3] Revise AGENTS.md --- AGENTS.md | 120 ++++++++++++++++++++++++++++++++++-------------------- 1 file changed, 75 insertions(+), 45 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 0c6f394c34..aac20017ad 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,59 +1,89 @@ # Jamulus — Agent Instructions -Real-time networked music jamming app. Qt/C++. Entry point: `src/main.cpp`. Configure `CONFIG` flags in `Jamulus.pro`. +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`. -## DO NOT edit (generated or third-party) -- `moc_*.cpp`, `ui_*.h`, `qrc_*.cpp` are generated at build time (moc/uic/rcc) — never hand-edit. -- `*.qm` under `.qm/` are committed compiled translations — never hand-edit (regenerate from the `.ts` sources). -- `libs/` is third-party (opus, oboe, NSIS). `libs/oboe` is a git submodule — run - `git submodule update --init` if it is empty. Do not apply clang format on any of those files. +**Make the smallest possible change. One logical change per PR. Never mix refactoring with fixes/features.** -## Build / verify -- Linux desktop: `qmake && make` (use `qmake-qt5` on Fedora). -- Headless server: `qmake "CONFIG+=headless serveronly" && make`. -- macOS: `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` to make it runnable. More infos: COMPILING.md. +Priority order: Stability > Low latency / real-time safety > Backwards compatibility > Maintainability > New features. + +Before editing code search and read the relevant doc below first. + +--- + +## Never Do + +- Block or slow: audio callbacks, socket handling, server mixing timers. +- Allocate excessive memory, do file I/O, or log excessively in real-time paths. +- Trust any value received from a remote client — validate size and bounds on all network input. +- Edit generated files: `moc_*.cpp`, `ui_*.h`, `qrc_*.cpp`, `*.qm`. +- Edit or reformat third-party code: `libs/` (opus, oboe, NSIS). +- Edit `ChangeLog` directly. +- Change architecture without discussion. + +## Build + +See `COMPILING.md`. + +Generally use: +```bash +git submodule update --init # required: oboe (Android) +qmake && make # Linux (use qmake-qt5 on Fedora) +qmake "CONFIG+=headless serveronly" && make # headless server +``` + +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 automated test suite. State in the PR what and how you tested. + +## Audio stack by platform + +- **macOS**: Core Audio (default). `CONFIG+=jackonmac` uses JACK (untested). +- **Linux**: JACK. On Windows: ASIO (default) or JACK (`CONFIG+=jackonwindows`). +- **iOS**: Core Audio iOS. Client-only build. +- **Android**: Oboe library (git submodule `libs/oboe`). Requires `git submodule update --init`. + +## Qt / portability + +- Minimum Qt: **5.12.2**. Qt 6.x.y recommended. Guard newer APIs with `#if QT_VERSION >= QT_VERSION_CHECK(...)`. +- C++11 (C++17 on Android for Oboe's `std::timed_mutex`). +- iOS builds require Qt 5.15 or later (Qt 6 is buggy for iOS). +- Preserve platform support. Don't break Android/iOS builds even if unofficial. +- Supported desktop: Windows 10+, macOS 10.10+, Ubuntu 20.04+/Debian 11+. ## Style (C / C++ / Obj-C++) -- Before committing `.cpp/.h/.mm` or after `qmake Jamulus.pro`, run `make clang_format`. -- **CI uses clang-format** (see `.github/workflows/coding-style-check.yml` - `clangFormatVersion` for version). -- Rules: tabs→4 spaces, braces on their own line, space inside `()` and around - `if/for/while` conditions, column limit 150, left pointer alignment (`int* p`). -- New files must carry an AGPL 3.0 (or later) license header. -- Existing pre-3.12.1 code being amended should already carry combined AGPL 3.0 and GPL 2.0 (or later) license blocks. - code is GPL 2.0+. - -## Tests -- No automated test suite. - -## Translations -- Use `tr ( "Hello %1" ).arg ( name )` — never concatenate translatable strings with `+`. -- Per-language `.ts` files live in `src/translation/`. -## JSON-RPC -- If you change RPC methods, regenerate `docs/JSON-RPC.md` with - `tools/generate_json_rpc_docs.py` (CI fails otherwise — `check-json-rpcs-docs.yml`). +```bash +make clang_format # run before commit (after qmake Jamulus.pro or before .cpp/.h/.mm commits) +``` -## Other tooling -- `.sh` files: lint with `shellcheck --shell=bash` and `shfmt -d`. -- Python (under `tools/`): max line length 99, run `pylint` (< 3.0) with `.pylintrc`. -- ChangeLog: put `CHANGELOG: ` in the PR description. Do **not** edit - the `ChangeLog` file (causes conflicts). +- **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/`. +- Rules: tabs→4 spaces, braces on own line, space inside `()` and around `if/for/while`, column limit 150, left pointer alignment (`int* p`). +- New files: AGPL 3.0+ license header. Pre-3.12.1dev code: GPL 2.0+ (dual-licensed as part of Jamulus). +- Use `tr ( "Hello %1" ).arg ( name )` for user-facing strings — never string concatenation. -## Version / portability constraints +## JSON-RPC -- Minimum Qt: **5.12**. Guard newer APIs with `#if QT_VERSION >= QT_VERSION_CHECK(...)`. -- Preserve C++11/17 and Android/iOS compatibility. +- Enabled by default unless `CONFIG+=nojsonrpc`. +- If you change RPC methods, 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 -- Branch named `autobuild/` triggers CI builds on your fork. -- Include `CHANGELOG:` line with a brief changelog discription and, for new deps/build changes, the - `AUTOBUILD: Please build all targets` tag. -## Before finishing +- Small changes preferred +- Branch `autobuild/` triggers CI builds on your fork. +- Include `CHANGELOG:` line with changelog description. For new deps/build changes, add `AUTOBUILD: Please build all targets`. + +## Before opening a PR + +One logical change per PR — no unrelated cleanup or reformatting of untouched code. Discuss features in an issue before implementing. See `CONTRIBUTING.md`. +Builds? Tested? **Smallest change possible?** + +## Read when relevant -- Do not modify generated or third-party files. -- Format code. -- Ensure changes build for the affected target(s). +- `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 From c4f44b9f713875132c15f64396d7bac06f57ad04 Mon Sep 17 00:00:00 2001 From: ann0see <20726856+ann0see@users.noreply.github.com> Date: Thu, 23 Jul 2026 16:42:42 +0200 Subject: [PATCH 3/3] Improve SNR --- AGENTS.md | 14 ++------------ 1 file changed, 2 insertions(+), 12 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index aac20017ad..384d52686d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -6,8 +6,6 @@ Real-time networked music jamming app. Qt/C++ qmake project. Client and server s Priority order: Stability > Low latency / real-time safety > Backwards compatibility > Maintainability > New features. -Before editing code search and read the relevant doc below first. - --- ## Never Do @@ -37,13 +35,6 @@ and `macdeployqt ./Release/Jamulus.app` (or `./Debug/Jamulus.app`) to make it ru No automated test suite. State in the PR what and how you tested. -## Audio stack by platform - -- **macOS**: Core Audio (default). `CONFIG+=jackonmac` uses JACK (untested). -- **Linux**: JACK. On Windows: ASIO (default) or JACK (`CONFIG+=jackonwindows`). -- **iOS**: Core Audio iOS. Client-only build. -- **Android**: Oboe library (git submodule `libs/oboe`). Requires `git submodule update --init`. - ## Qt / portability - Minimum Qt: **5.12.2**. Qt 6.x.y recommended. Guard newer APIs with `#if QT_VERSION >= QT_VERSION_CHECK(...)`. @@ -66,15 +57,14 @@ make clang_format # run before commit (after qmake Jamulus.pro or before .cpp/ ## JSON-RPC -- Enabled by default unless `CONFIG+=nojsonrpc`. - If you change RPC methods, 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 -- Small changes preferred +- Small changes preferred, every change tested - Branch `autobuild/` triggers CI builds on your fork. -- Include `CHANGELOG:` line with changelog description. For new deps/build changes, add `AUTOBUILD: Please build all targets`. +- Follow `.github/pull_request_template.md`. Include `CHANGELOG:` line with changelog description. For new deps/build changes, add `AUTOBUILD: Please build all targets`. ## Before opening a PR