mirror of https://github.com/ether/etherpad-lite.git synced 2026-04-04 21:22:20 +02:00

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)

2026-03-04 21:03:58 +00:00

3.1 KiB

Raw Blame History

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.

3.1 KiB Raw Blame History