Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
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
24 changes: 24 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
@@ -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.
12 changes: 12 additions & 0 deletions contribute/en/Style-and-Tone.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

<details markdown="1">
Expand Down Expand Up @@ -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:
Expand Down
Loading