Skip to content

Latest commit

 

History

History
61 lines (48 loc) · 3.06 KB

AGENTS.MD

File metadata and controls

61 lines (48 loc) · 3.06 KB

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.