From 4d80659fc8524f2aef0d2c9f4df286bb00a32a6c Mon Sep 17 00:00:00 2001 From: John McLear Date: Wed, 4 Mar 2026 21:03:58 +0000 Subject: [PATCH] docs: add AGENTS.MD for AI and developer guidance (#7348) * docs: add AGENTS.MD for AI and developer guidance * docs: update project name from Etherpad Lite to Etherpad * docs: fix incorrect test directory path in AGENTS.MD * docs: correct test stack description in AGENTS.MD (Mocha is primary) * docs: fix incorrect easysync documentation path in AGENTS.MD * chore: add .pr_agent.toml to enable automatic PR review/description on push * docs: remove nodejs version from README and AGENTS.MD (prefer package.json) * docs: standardize all indentation to 2 spaces * chore: update src/package.json node engine to match root (>=20.0.0) --- .pr_agent.toml | 5 ++++ AGENTS.MD | 61 +++++++++++++++++++++++++++++++++++++++++++++++ CONTRIBUTING.md | 2 +- README.md | 2 +- best_practices.md | 2 +- src/package.json | 2 +- 6 files changed, 70 insertions(+), 4 deletions(-) create mode 100644 .pr_agent.toml create mode 100644 AGENTS.MD diff --git a/.pr_agent.toml b/.pr_agent.toml new file mode 100644 index 000000000..93e106ea2 --- /dev/null +++ b/.pr_agent.toml @@ -0,0 +1,5 @@ +[pr_reviewer] +run_on_pr_sync = true + +[pr_description] +run_on_pr_sync = true diff --git a/AGENTS.MD b/AGENTS.MD new file mode 100644 index 000000000..ec9637b39 --- /dev/null +++ b/AGENTS.MD @@ -0,0 +1,61 @@ +# Agent Guide - Etherpad + +Welcome to the Etherpad project. This guide provides essential context and instructions for AI agents and developers to effectively contribute to the codebase. + +## Project Overview +Etherpad is a real-time collaborative editor designed to be lightweight, scalable, and highly extensible via plugins. + +## Technical Stack +- **Runtime:** Node.js +- **Package Manager:** pnpm +- **Languages:** TypeScript (primary), JavaScript, CSS, HTML +- **Backend:** Express.js, Socket.io +- **Frontend:** Legacy core (`src/static`), New UI (`ui/`), Admin UI (`admin/`) +- **Build Tools:** Vite (for `ui` and `admin`), custom scripts in `bin/` +- **Testing:** Mocha (Backend), Vitest, Playwright, custom backend test suite + +## Directory Structure +- `src/node/`: Backend logic, API, and database abstraction. +- `src/static/`: Core frontend logic (Legacy). +- `ui/`: Modern React-based user interface. +- `admin/`: Modern React-based administration interface. +- `bin/`: Utility and lifecycle scripts. +- `doc/`: Documentation in Markdown and Adoc formats. +- `src/tests/`: Test suites (backend, frontend, UI, admin). +- `var/`: Runtime data (logs, dirtyDB, etc. - ignored by git). +- `local_plugins/`: Directory for developing and testing plugins locally. + +## Core Mandates & Conventions + +### Coding Style +- **Indentation:** 2 spaces for all files (JS/TS/CSS/HTML). +- **No Tabs:** Use spaces only. +- **Comments:** Provide clear comments for complex logic. +- **Backward Compatibility:** Always ensure compatibility with older versions of the database and configuration files. + +### Development Workflow +- **Branching:** Work in feature branches. Issue PRs against the `develop` branch. +- **Commits:** Maintain a linear history (no merge commits). Use meaningful messages in the format: `submodule: description`. +- **Feature Flags:** New features should be placed behind feature flags and disabled by default. +- **Deprecation:** Never remove features abruptly; deprecate them first with a `WARN` log. + +### Testing & Validation +- **Requirement:** Every bug fix MUST include a regression test in the same commit. +- **Backend Tests:** Run `pnpm --filter ep_etherpad-lite run test` from the root. +- **Frontend Tests:** Accessible at `/tests/frontend` on a running instance. +- **Linting:** Run `pnpm run lint` to ensure style compliance. +- **Build:** Run `pnpm run build:etherpad` before production deployment. + +## Key Concepts + +### Easysync +The real-time synchronization engine. It is complex; refer to `doc/public/easysync/` before modifying core synchronization logic. + +### Plugin Framework +Most functionality should be implemented as plugins (`ep_...`). Avoid modifying the core unless absolutely necessary. + +### Settings +Configured via `settings.json`. A template is available at `settings.json.template`. Environment variables can override any setting using `"${ENV_VAR}"` or `"${ENV_VAR:default_value}"`. + +## AI-Specific Guidance +AI/Agent contributions are explicitly welcomed by the maintainers, provided they strictly adhere to the guidelines in `CONTRIBUTING.md` and this guide. Always prioritize stability, readability, and compatibility. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 19b5ff95c..2a6f384fc 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -83,7 +83,7 @@ Also, keep it maintainable. We don't wanna end up as the monster Etherpad was! ## Coding style * Do write comments. (You don't have to comment every line, but if you come up with something that's a bit complex/weird, just leave a comment. Bear in mind that you will probably leave the project at some point and that other people will read your code. Undocumented huge amounts of code are worthless!) * Never ever use tabs -* Indentation: JS/CSS: 2 spaces; HTML: 4 spaces +* Indentation: 2 spaces * Don't overengineer. Don't try to solve any possible problem in one step, but try to solve problems as easy as possible and improve the solution over time! * Do generalize sooner or later! (if an old solution, quickly hacked together, poses more problems than it solves today, refactor it!) * Keep it compatible. Do not introduce changes to the public API, db schema or configurations too lightly. Don't make incompatible changes without good reasons! diff --git a/README.md b/README.md index 3719ecda7..492ad015d 100644 --- a/README.md +++ b/README.md @@ -100,7 +100,7 @@ volumes: ### Requirements -[Node.js](https://nodejs.org/) >= **18.18.2**. +[Node.js](https://nodejs.org/). ### Windows, macOS, Linux diff --git a/best_practices.md b/best_practices.md index 51c3729cd..bdfbef4ec 100644 --- a/best_practices.md +++ b/best_practices.md @@ -85,7 +85,7 @@ Also, keep it maintainable. We don't wanna end up as the monster Etherpad was! ## Coding style * Do write comments. (You don't have to comment every line, but if you come up with something that's a bit complex/weird, just leave a comment. Bear in mind that you will probably leave the project at some point and that other people will read your code. Undocumented huge amounts of code are worthless!) * Never ever use tabs -* Indentation: JS/CSS: 2 spaces; HTML: 4 spaces +* Indentation: 2 spaces * Don't overengineer. Don't try to solve any possible problem in one step, but try to solve problems as easy as possible and improve the solution over time! * Do generalize sooner or later! (if an old solution, quickly hacked together, poses more problems than it solves today, refactor it!) * Keep it compatible. Do not introduce changes to the public API, db schema or configurations too lightly. Don't make incompatible changes without good reasons! diff --git a/src/package.json b/src/package.json index 66eef273e..fc1e7a29c 100644 --- a/src/package.json +++ b/src/package.json @@ -123,7 +123,7 @@ "vitest": "^4.0.18" }, "engines": { - "node": ">=18.18.2", + "node": ">=20.0.0", "npm": ">=6.14.0", "pnpm": ">=8.3.0" },