From 69da13c340fbfd42c7216666159ef09c8a16f255 Mon Sep 17 00:00:00 2001 From: jrd Date: Tue, 21 Jul 2026 18:58:31 +0000 Subject: [PATCH 1/3] Add AGENTS.md for AI-agent contributors MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Points agents at the existing README workflow and Style-and-Tone guide, and adds one rule not covered by either: no smart/curly quotes or apostrophes, since a curly character silently corrupts shell single-quoted strings, JSON, regexes, and code spans in a way plain ASCII never does. πŸ€– Generated with Claude Code --- AGENTS.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 000000000..e32f3e078 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,19 @@ +# Jamulus Website β€” Agent Instructions + +Content repo for jamulus.io (wiki/docs). English is the source of truth β€” edits land in English first, then flow to other languages via Weblate/po4a. + +Docs: [README.md](README.md) (workflow, translation process, branch targeting), [Style and Tone guide](https://jamulus.io/contribute/Style-and-Tone) (voice, terminology, capitalisation β€” applies to agents without exception). + +## Rules + +- Smallest possible PRs: one logical change each. +- Edit English source `.md` files only β€” never hand-edit translated-language files or `.po` files; those belong to translators via Weblate. +- **No smart/curly quotes or apostrophes** (`’ β€œ ”`) β€” always straight ASCII `'` and `"`. This isn't a style preference: a curly character pasted into a shell single-quoted string, JSON, a regex, or a code span is not the character the parser expects, and corrupts it silently. Word/Google Docs autocorrect and some LLM output insert these by default β€” check for them explicitly before opening a PR, especially near any code span or CLI example. +- Prefer hedged phrasing over absolute claims where the claim isn't a hard limit (e.g. "discouraged" over "not recommended", "up to N" over "less than N") β€” follows the guide's "give solutions first, avoid overly stylised language" principle. +- British English spelling (colour, minimise, centre). +- Match established terminology exactly: Server/Client (capitalised = a Jamulus app instance) vs. server/client (lowercase = the physical/cloud machine); "person" not "musician"; "sound card" vs. "audio interface" β€” full list in Style-and-Tone.md. + +## Submit + +- Target `next-release` if the change needs translation, `release` if not (README's workflow section explains which). +- Fill out the PR template checklist. From f9d0214ead03aec32648825e3026f51a2a640acc Mon Sep 17 00:00:00 2001 From: jrd Date: Thu, 23 Jul 2026 19:07:23 +0000 Subject: [PATCH 2/3] Expand quotes rule into a full Punctuation section Moves the substantive dash/hyphen/quote/ellipsis guidance into Style-and-Tone.md (applies to all contributors, not just agents) next to the existing Units section, which does the same kind of micro-convention work. AGENTS.md keeps a pointer plus the one rule that's genuinely agent-specific: check the diff for stray curly characters near code, since that's an LLM/paste failure mode rather than a human typing habit. Unifies the two prior asks in this area: the original "always straight ASCII" quotes rule (safe wherever the text could be pasted into a shell/JSON/regex/code span) and the "use en/em dash where typography calls for it" split from PR #1159, under one principle -- machine context stays ASCII, human-read prose gets the correct character. --- AGENTS.md | 2 +- contribute/en/Style-and-Tone.md | 15 +++++++++++++++ 2 files changed, 16 insertions(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index e32f3e078..78edb387f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -8,7 +8,7 @@ Docs: [README.md](README.md) (workflow, translation process, branch targeting), - Smallest possible PRs: one logical change each. - Edit English source `.md` files only β€” never hand-edit translated-language files or `.po` files; those belong to translators via Weblate. -- **No smart/curly quotes or apostrophes** (`’ β€œ ”`) β€” always straight ASCII `'` and `"`. This isn't a style preference: a curly character pasted into a shell single-quoted string, JSON, a regex, or a code span is not the character the parser expects, and corrupts it silently. Word/Google Docs autocorrect and some LLM output insert these by default β€” check for them explicitly before opening a PR, especially near any code span or CLI example. +- **Punctuation**: follow the Punctuation section in Style-and-Tone.md (dash/hyphen choice, curly vs. straight quotes, ellipsis). Word/Google Docs autocorrect and some LLM output insert curly characters by default even inside code β€” before opening a PR, check your diff specifically for stray curly quotes/dashes near any code span, CLI example, or other machine-parsed value. - Prefer hedged phrasing over absolute claims where the claim isn't a hard limit (e.g. "discouraged" over "not recommended", "up to N" over "less than N") β€” follows the guide's "give solutions first, avoid overly stylised language" principle. - British English spelling (colour, minimise, centre). - Match established terminology exactly: Server/Client (capitalised = a Jamulus app instance) vs. server/client (lowercase = the physical/cloud machine); "person" not "musician"; "sound card" vs. "audio interface" β€” full list in Style-and-Tone.md. diff --git a/contribute/en/Style-and-Tone.md b/contribute/en/Style-and-Tone.md index 197d2d6b6..ac4bf0526 100644 --- a/contribute/en/Style-and-Tone.md +++ b/contribute/en/Style-and-Tone.md @@ -101,6 +101,21 @@ Jamulus is "Free and Open Source (FOSS)" (not "free software" or "open source") "Server List" This is the list of Servers maintained by a Directory. A Server registers with a Directory to be _listed_ in that Directory’s _server list_. +## Punctuation + +One governing question for every dash, quote, or ellipsis: is this character doing a job a parser depends on, or is it doing prose work for a human reader? Machine-context wins every time; only prose gets the fancier character. + +Never use a curly/typographic character inside a code span or fenced code block, an HTML attribute, YAML frontmatter, a CLI flag, a Markdown list/checkbox bullet, an ISO 8601 date (`2021-03-17`), a version/build string (`3.7.0dev-123456`), a URL, or anything meant to be copied and pasted verbatim (a shell command, a JSON snippet, a config value). In all of these, a smart quote, em-dash, or en-dash is either a parser error or a silent corruption of a value the reader will paste elsewhere. Plain ASCII `-`, `'`, `"` only. + +Everywhere else β€” prose meant to be read, not executed β€” use the correct typographic character: + +- **Hyphen (`-`)**: compound modifiers only (`low-bandwidth`, `text-wrapping`). If you can mentally replace it with "to" or read it as a parenthetical break, it isn't a hyphen's job. +- **En dash (`–`), no surrounding spaces**: numeric ranges (`0–16`, `30–50 ms`, `pages 16–18`). +- **En dash (`–`), with spaces**: a "Title – Subtitle" page title, matching the existing pattern in `Command-Line-Options.md`, `Privacy-Statement.md`, and `2020-03-28-Server-Rpi.md`. +- **Em dash (`β€”`), with spaces on both sides**: a parenthetical aside, appositive, or sentence interruption β€” matches the site's own pre-existing usage (`misc/1-index.md`). Never use a doubled hyphen (`--`) as a substitute; it's a typewriter-era workaround, not a typographic period. +- **Curly quotes/apostrophes (`’ β€œ ”`)**: prose, including quoted UI labels read by a human (`click "Learn"`) β€” never a value the reader is meant to type or paste. +- **Ellipsis**: use the single `…` character in narrative prose. Exception β€” when quoting an app's literal UI string that itself ends in three dots (`"File > Connection Setup..."`, `"My Profile..."`), reproduce it exactly; don't "correct" a real menu label. + ## Units We use the following abbreviations: From 7e7b83f9548d831d9b962128529895c047b2e195 Mon Sep 17 00:00:00 2001 From: jrd Date: Thu, 23 Jul 2026 19:40:43 +0000 Subject: [PATCH 3/3] Clarify release vs next-release targeting is case-by-case Per ann0see's review comment on #1157: there's no reliable file-type rule for branch targeting. release publishes immediately and is auto-merged into next-release by CI (.github/workflows/main.yml); next-release only ships at the next release cutover. Point agents at checking recent PR precedent instead of a false-confidence heuristic, and default to the cheaper-to-correct branch when still unsure. --- AGENTS.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 78edb387f..6e5648114 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -15,5 +15,7 @@ Docs: [README.md](README.md) (workflow, translation process, branch targeting), ## Submit -- Target `next-release` if the change needs translation, `release` if not (README's workflow section explains which). +- Branch targeting is genuinely case by case (maintainers' own assessment) β€” there's no reliable rule like "translated content β†’ next-release." Mechanically: a merge to `release` publishes to production immediately and is auto-merged forward into `next-release` (see `.github/workflows/main.yml`); `next-release` only reaches production later, when a maintainer opens a release PR and squashes it into `release`. So the real question is "should this go live right now, or wait for the next release cutover?", not what kind of file you touched β€” `contribute/en/` and `_posts/` changes have gone directly to `release` in some PRs and to `next-release` in others. +- Before opening the PR, check recent precedent for files like the ones you're touching, e.g. `gh pr list --repo jamulussoftware/jamuluswebsite --base release --state merged --limit 30 --json title,files` and the same with `--base next-release`. If you still can't tell, say so explicitly in the PR description and let a maintainer redirect it rather than guessing silently. +- When truly unsure and precedent doesn't settle it, default to `next-release` β€” an off-base call there is cheap to correct before it ever goes live, unlike one on `release`. - Fill out the PR template checklist.