diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 000000000..094513361 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,24 @@ +# Jamulus Website - Agent Instructions + +Content repo for jamulus.io. English is the source of truth: edits land in English first, then flow to other languages via Weblate/po4a. + +Read first: [README.md](README.md) (workflow, translation, branches) and the [Style and Tone guide](https://jamulus.io/contribute/Style-and-Tone) (voice, terminology, spelling). The guide governs; this file does not restate or override it. + +## Changes + +This is documentation, not code. The bar is: **is this better than what is there now?** Not complete, not final - better. A page that answers a reader's question one step sooner is worth submitting on its own. + +- One logical improvement per PR. Open several small PRs rather than one large one, and keep each reviewable. +- Never hold a documentation fix behind a code change. Pages ship on their own schedule. +- If you cannot tell whether your version is better, say so in the PR description instead of guessing. + +## Rules + +- Edit English source `.md` files only. Never hand-edit translated files or `.po` files - those belong to translators via Weblate. +- Plain ASCII (`-` `'` `"`) inside anything parsed or copy-pasted: code, CLI flags, URLs, frontmatter, dates, versions. Autocorrect and LLM output break this by default; check your diff. See the Punctuation section of the Style and Tone guide. +- British English spelling (colour, minimise, centre). + +## Submitting + +- Branch: `next-release` unless you have a reason. `release` is the live site and publishes immediately; `next-release` waits for the next release cutover. Anything under `wiki/` must go to `next-release` - it is the only tree that gets translated, and it has to wait for the translation sprint. Blog posts under `_posts/` and urgent build fixes go to `release`. +- Fill out the PR template checklist. diff --git a/contribute/en/Style-and-Tone.md b/contribute/en/Style-and-Tone.md index 197d2d6b6..5ac634e93 100644 --- a/contribute/en/Style-and-Tone.md +++ b/contribute/en/Style-and-Tone.md @@ -10,6 +10,8 @@ permalink: "/contribute/Style-and-Tone" While contributing to Jamulus or the website, you should also keep style and tone in mind. Have a look at the following guidelines. +These guidelines apply to every contribution, including work drafted with AI assistance. The `AGENTS.md` file in the website repository points automated contributors here rather than repeating them, so this page stays the single source of truth. + **Note:** It is very important to thoroughly proofread content before submitting it, as any corrections made later have a knock-on effect on translations.
@@ -101,6 +103,16 @@ 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 + +Content here is written for people, but parts of it are read by tools as well. Keep the two apart. + +Inside anything a reader will copy or a tool will parse - code spans and fenced blocks, command-line flags, URLs, file paths, YAML frontmatter, HTML attributes, dates and version strings - use plain ASCII `-`, `'` and `"` only. A curly quote or a long dash pasted into a shell command, a config file or a search box is not the character the tool expects, and it fails in ways the reader cannot see. Word processors and AI writing tools insert those characters automatically, so check your work before submitting. + +In prose, plain ASCII is the safe default and most pages already use it. Where a typographic character genuinely helps the reader it is acceptable, but it is never required. Do not convert a page from one style to the other as a change of its own: that produces a large diff with no benefit to the reader, and churn for translators. + +When quoting a literal label from the app, reproduce it exactly, including any trailing dots ("File > Connection Setup..."). Do not correct a real menu label. + ## Units We use the following abbreviations: