tiptap: Instructions file for Codex

Tiptap

Headless rich text editor toolkit built on ProseMirror. A monorepo of small packages: a framework-agnostic core and extensions, plus React and Vue bindings.

Published packages live in packages/*. demos/ is a Vite app used as playground and as the target for e2e tests. All scripts are in the root package.json.

Rules

• Small, single-purpose diffs. Ask the user to review. Never autocommit.
• Add a changeset for user-facing changes. Public API breaks need a major bump and migration notes.
• Add or update a demo and tests for user-visible behavior. Prefer unit tests over e2e when deterministic.
• Fix fallow findings your change introduced. Don't suppress them.
• Comments should be clear, concise and use plain, simple english.
  • Rather use a oneliner
  • Try to always be intent-focused
  • stay local with comments
  • scannable, no long or complex wording
  • assume the reader doesn't know what you're talking about

Before opening a PR

vp run lint
vp run build
vp run test:unit
vp run test:e2e
vp run fallow:audit   # verdict must be pass or warn, never fail

Single package failing types: vp run -F @tiptap/core build. Dependency or lockfile errors: vp run reset, then rebuild.

PR scope and descriptions

• Each PR solves one clearly named problem. Split unrelated fixes, cleanup and refactors into separate PRs.
• Use .github/pull_request_template.md as written. Keep its headings and checklist. Put the explanation in Changes and Review.
• Write the title around the problem fixed or behavior added. A reviewer should understand the purpose without opening the diff.
• Keep Changes and Review to 2–4 short sentences or at most 4 short bullets. Start with the user-visible problem and when it happens, then explain the resulting behavior and how to verify it.
• Describe behavior in plain English. Include implementation details only when they explain a necessary design choice or risk.
• Leave file-by-file summaries, function inventories, line numbers and code walkthroughs in the diff. Name a file or symbol only when the reviewer needs it to locate a specific concern.
• Use backticks only for literal code, commands and necessary API names. Prefer plain sentences and simple bullets over bold labels, tables, decorative emoji and extra headings.
• Summarize relevant testing in one short sentence. Name what was checked and the result. Omit test totals, pass/skip counts, terminal output and lists of routine checks.
• Give a short reproduction step or link to a demo, test or CI result when it helps the reviewer verify the change. For visual bugs, prefer a useful screenshot or short recording.
• Include performance numbers only with a reproducible benchmark and a link to its setup and results. Include exact dimensions or other measurements only when they explain the bug or requirement.
• State failed or missing checks, known limitations and breaking changes plainly. Add only the detail needed to explain the impact, risk or migration, even when that requires exceeding the short description limit.
• Report only checks actually run and results actually observed. Never turn an assumption or an unchecked checklist item into a success claim.
• Keep AI disclosures brief and honest. The author must review and understand the diff before requesting review. Never check the responsibility box on the author's behalf.
• Remove work logs, repeated responsibility statements, generic praise for the change and stock offers to do more.
• Before requesting review, read the description without the diff. It must answer: What breaks or is missing? What changes for the user? How can I check it? Cut anything that does not help answer those questions or explain a material risk.