mirror of
https://github.com/ether/etherpad-lite.git
synced 2026-04-17 19:41:21 +02:00
4d80659fc8
* 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)
62 lines
3.1 KiB
Markdown
62 lines
3.1 KiB
Markdown
# 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.
|