Skip to content

Add agent instructions for Jamulus #3785

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
ann0see wants to merge 3 commits into
base: main
Choose a base branch
from
+81 −0
Open

Add agent instructions for Jamulus #3785

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
e140acb
Add agent instructions for Jamulus and update CONTRIBUTING.md
ann0see Jul 21, 2026
282f29a
Revise AGENTS.md
ann0see Jul 23, 2026
c4f44b9
Improve SNR
ann0see Jul 23, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
79 changes: 79 additions & 0 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,79 @@
# 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.

---

## 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)

@pljones pljones Jul 30, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I usually run a make distclean (which is allowed to error if the Makefile's gone) to start completely afresh.

qmake "CONFIG+=headless serveronly" && make # headless server

@pljones pljones Jul 30, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I usually run make clean after I've finished working.

(One thing this means is I've noticed how messy the Android build leaves the working directory...)

@ann0see ann0see Jul 31, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

MacOS and iOS are also messy.

@pljones pljones Jul 31, 2026 •
edited
Loading

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

OK, I guess this is another housekeeping task we need on a new PR.

I'm envisaging:

  • checkout the git repo to a fresh directory
  • new temporary step:
    • store the directory listing
  • run all the build steps
  • new temporary step:
    • make clean (or platform-appropriate command)
    • store the directory listing again
    • compare the two directory listings

Then pass the cruft listing to an LLM to raise a PR to fix the "make clean" scope.

```

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.

## 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`).

@ann0see ann0see Jul 28, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- C++11 (C++17 on Android for Oboe's `std::timed_mutex`).
- C++11 (C++17 on Android).

- 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+.

@ann0see ann0see Jul 28, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

May get out of date.

@pljones pljones Jul 29, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think some high-level guidance for contributors is needed somewhere other than in the AutoBuild workflow itself. Whether that's here or somewhere else, though, is open to debate. Probably somewhere else?

@mcfnord mcfnord Jul 29, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is the right level of specificity in the right place (AGENTS.md, aka the Bible). The plusses provide a lot of future-proofing. I want every agent to remember these platform commitments every time it considers doing something to the code. Omitting this guidance is inviting agents to forget about a platform in a solution attempt, or to guess which platforms we support. If/when Qt 6 becomes viable, we will be happy to update AGENTS.md to say so.

@pljones pljones Jul 30, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

OK. Sounds reasonable.

Do we have an expanded version with the history behind each decision written down, I wonder? We should -- though that isn't for here.


## Style (C / C++ / Obj-C++)

```bash
make clang_format # run before commit (after qmake Jamulus.pro or before .cpp/.h/.mm commits)
```

- **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).

@pljones pljones Jul 30, 2026 •
edited
Loading

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

GPL 2.0+ -> we've taken the "or later" and moved everything to GPL 3.0+ as of 3.12.1dev.

So you'd have to git reset --hard before that version to checkout older code.

Also the intent is stated that all new contributions are AGPL 3.0+, not only to new files. It's only the code that was there prior to the move to AGPL3.0+ that is now GPL3.0+.

- Use `tr ( "Hello %1" ).arg ( name )` for user-facing strings — never string concatenation.

## JSON-RPC

- 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, every change tested
- Branch `autobuild/<name>` triggers CI builds on your fork.

@pljones pljones Jul 30, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

(The "/" isn't actually needed by the regex, IIRC -- anything autobuild.*)

- Follow `.github/pull_request_template.md`. Include `CHANGELOG:` line with changelog description. For new deps/build changes, add `AUTOBUILD: Please build all targets`.

@pljones pljones Jul 30, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Might be worth stating which targets are in without this and which this adds. Presumably the occasional fix to actual code (not deps / build process) will need this.


## 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?**

@pljones pljones Jul 30, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Add Self-reviewed against "Priority order" above? maybe.


## 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
2 changes: 2 additions & 0 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
Loading