[*] Chore: require all changes to be backwards compatible#8634
Conversation
Add a Backwards Compatibility section to AGENTS.md (and a pointer in CLAUDE.md) so AI agents and automated tools working in this repo know that all changes must preserve existing public APIs, behavior, and the EditorState/node JSON serialization format. Lexical is a widely-adopted OSS library, so breaking changes affect every downstream consumer. Agents should add new APIs alongside old ones and deprecate rather than remove.
potatowagon
requested review from
acywatson,
etrepum,
fantactuka,
ivailop7 and
zurfyx
as code owners
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
meta-cla
Bot
added
the
CLA Signed
potatowagon
changed the title
|
|
||
| ## Backwards Compatibility | ||
|
|
||
| **All changes MUST be backwards compatible.** Do not remove or rename existing public APIs, change their signatures/behavior, or break the `EditorState`/node JSON serialization format. Add new APIs alongside old ones and deprecate rather than delete. See the [Backwards Compatibility section in AGENTS.md](./AGENTS.md#backwards-compatibility) for details. |
There was a problem hiding this comment.
This seems redundant, if we are worried that claude isn't reading AGENTS.md maybe we should switch this file to a symlink instead?
There was a problem hiding this comment.
Good call — done in 25712e5. Replaced CLAUDE.md with a symlink to AGENTS.md (git mode 120000) so there's a single source of truth and the two can't drift. The Backwards Compatibility section lives only in AGENTS.md now.
There was a problem hiding this comment.
Update: reverted all changes to CLAUDE.md in e1e71f8 — it's now identical to main. This PR now only touches AGENTS.md, so there's no longer any duplication to worry about. (Disregard the earlier symlink commit; it's been backed out.)
There was a problem hiding this comment.
Raised the symlink as its own PR so you can evaluate it independently: #8643. It's off main, single-file change (CLAUDE.md → AGENTS.md, mode 120000). I noted the Windows core.symlinks caveat in the description — take it or leave it, no strong opinion from my side. This PR (#8634) stays scoped to just the AGENTS.md backwards-compat doc.
There was a problem hiding this comment.
made this its own PR so it's super easy to revert on its own if the symlink turns out to be finicky : https://github.com/facebook/lexical/pull/8643/changes,
Per review feedback (etrepum): the duplicated Backwards Compatibility text in CLAUDE.md was redundant. Replace the file with a symlink to AGENTS.md so Claude Code reads the single source of truth and the two files can never drift.
Restore CLAUDE.md to its original state on main. The backwards-compat guidance lives solely in AGENTS.md now; CLAUDE.md is left untouched.
2 participants
Description
This PR updates the AI agent guidance docs (
AGENTS.mdandCLAUDE.md) to make explicit that all changes made to the Lexical codebase must be backwards compatible.Lexical is a widely-adopted OSS library, so breaking changes ripple out to every downstream consumer. Agents and automated tools working in this repo should know to:
$functions — add new APIs alongside the old ones.EditorState/ node JSON serialization format so older content keeps deserializing.Changes
AGENTS.md: new Backwards Compatibility section before "Important Development Notes".CLAUDE.md: a short pointer to the same rule for Claude Code, linking back toAGENTS.md.Docs-only change — no code or test impact.