From 65f5c10755769acb5f17acda4dc0adee1003b24b Mon Sep 17 00:00:00 2001 From: John McLear Date: Sat, 9 May 2026 16:38:40 +0100 Subject: [PATCH 1/2] 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 | 193 +++++++++++++++++------------------------------- 1 file changed, 67 insertions(+), 126 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 724e02a..025e72f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,133 +1,74 @@ -# Contributor Guidelines -(Please talk to people on the mailing list before you change this page, see our section on [how to get in touch](https://github.com/ether/etherpad-lite#get-in-touch)) - -## Pull requests - -* the commit series in the PR should be _linear_ (it **should not contain merge commits**). This is necessary because we want to be able to [bisect](https://en.wikipedia.org/wiki/Bisection_(software_engineering)) bugs easily. Rewrite history/perform a rebase if necessary -* PRs should be issued against the **develop** branch: we never pull directly into **master** -* PRs **should not have conflicts** with develop. If there are, please resolve them rebasing and force-pushing -* when preparing your PR, please make sure that you have included the relevant **changes to the documentation** (preferably with usage examples) -* contain meaningful and detailed **commit messages** in the form: - ``` - submodule: description - - longer description of the change you have made, eventually mentioning the - number of the issue that is being fixed, in the form: Fixes #someIssueNumber - ``` -* if the PR is a **bug fix**: - * the first commit in the series must be a test that shows the failure - * subsequent commits will fix the bug and make the test pass - * the final commit message should include the text `Fixes: #xxx` to link it to its bug report -* think about stability: code has to be backwards compatible as much as possible. Always **assume your code will be run with an older version of the DB/config file** -* if you want to remove a feature, **deprecate it instead**: - * write an issue with your deprecation plan - * output a `WARN` in the log informing that the feature is going to be removed - * remove the feature in the next version -* if you want to add a new feature, put it under a **feature flag**: - * once the new feature has reached a minimal level of stability, do a PR for it, so it can be integrated early - * expose a mechanism for enabling/disabling the feature - * the new feature should be **disabled** by default. With the feature disabled, the code path should be exactly the same as before your contribution. This is a __necessary condition__ for early integration -* think of the PR not as something that __you wrote__, but as something that __someone else is going to read__. The commit series in the PR should tell a novice developer the story of your thoughts when developing it - -## How to write a bug report - -* Please be polite, we all are humans and problems can occur. -* Please add as much information as possible, for example - * client os(s) and version(s) - * browser(s) and version(s), is the problem reproducible on different clients - * special environments like firewalls or antivirus - * host os and version - * npm and nodejs version - * Logfiles if available - * steps to reproduce - * what you expected to happen - * what actually happened -* Please format logfiles and code examples with markdown see github Markdown help below the issue textarea for more information. - -If you send logfiles, please set the loglevel switch DEBUG in your settings.json file: +# Contributing to ep_reference +Thanks for helping improve `ep_reference` — 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/.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 `