From d8e330c7d27c9e7fe67154b3f986a6440ee20871 Mon Sep 17 00:00:00 2001
From: John McLear <john@mclear.co.uk>
Date: Sat, 9 May 2026 16:33:41 +0100
Subject: [PATCH] docs: rewrite CONTRIBUTING.md for plugin scope

Replaces the etherpad-lite-era boilerplate with a plugin-specific
guide: target branch is main, local install via
pnpm run plugins i --path, tests run via the etherpad harness,
and i18n/a11y are now standing requirements.
---
 CONTRIBUTING.md | 74 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 74 insertions(+)
 create mode 100644 CONTRIBUTING.md

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..d9fbe12
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,74 @@
+# Contributing to ep_ai_chat
+
+Thanks for helping improve `ep_ai_chat` — a plugin for [Etherpad](https://etherpad.org/). LLM/Agent contributions are explicitly welcome, provided they follow the rules below.
+
+For shared rules that apply to all Etherpad code (linear commits, deprecation policy, feature flags, stability guarantees), please read [ether/etherpad's CONTRIBUTING.md](https://github.com/ether/etherpad/blob/develop/CONTRIBUTING.md). This document only covers what's specific to plugin work.
+
+## Plugin-specific rules
+
+* **Target branch:** PRs go to `main` on this repo. Plugin repos do not use git-flow's `develop` branch.
+* **Linear commits, no merge commits.** Rebase if needed.
+* **Every bug fix must include a regression test in the same commit.**
+* **Internationalization (i18n):** every user-facing string lives in `locales/<lang>.json` and is referenced via `data-l10n-id` in templates or `html10n.get(key)` in code. No hardcoded English in markup.
+* **Accessibility (a11y):** no nested interactive elements (no `<button>` inside `<a>`); every interactive control has an accessible name; keyboard focus order matches visual order. Note that on icon-only controls you should rely on Etherpad's html10n to populate `aria-label` from the `data-l10n-id` translation — adding a hardcoded English `aria-label` blocks that and leaves the control untranslated.
+
+## Local development
+
+`ep_ai_chat` is a plugin, so you develop it inside a checkout of [ether/etherpad](https://github.com/ether/etherpad).
+
+```bash
+# Once: clone etherpad alongside this repo
+git clone https://github.com/ether/etherpad.git
+cd etherpad
+pnpm install
+
+# Install ep_ai_chat from your local clone
+pnpm run plugins i --path ../ep_ai_chat
+
+# Start the dev server (port 9001)
+pnpm --filter ep_etherpad-lite run dev
+```
+
+Edits in `../ep_ai_chat/` are picked up after a server restart.
+
+## Tests
+
+Tests live inside this repo and are executed by Etherpad's test harness:
+
+* Backend (Mocha): `static/tests/backend/specs/`
+* Playwright (frontend E2E): `static/tests/frontend-new/specs/`
+
+Run them from the etherpad checkout:
+
+```bash
+# Backend (no separate server needed, harness boots one)
+pnpm --filter ep_etherpad-lite run test
+
+# Playwright (requires `pnpm run dev` in another terminal)
+pnpm --filter ep_etherpad-lite run test-ui
+```
+
+Lint locally before pushing:
+
+```bash
+pnpm run lint
+```
+
+## Coding style
+
+* JS/CSS/HTML: 2 spaces, no tabs.
+* `pnpm run lint` must pass (configured via `eslint-config-etherpad`).
+* Avoid breaking changes to public hooks, the line-attribute storage shape, or HTML export output. The backend export spec enforces a stable shape.
+
+## Bug reports
+
+Please include:
+
+* Etherpad version, ep_ai_chat version, browser + OS
+* Steps to reproduce
+* What you expected, what actually happened
+* Server log excerpt (set `"loglevel": "DEBUG"` in `settings.json` for verbose output)
+
+## AI agents
+
+If you are an LLM/agent contributor, also read [`AGENTS.md`](AGENTS.md) — it documents the file layout, helper usage, and standing rules for autonomous edits.