Contributing to RoamJS

Thank you for your interest in contributing to RoamJS! We welcome any contributions to the code base and the documentation.

Create an Issue!

Before submitting a pull request, it is strongly recommended to create an issue first to discuss your proposed changes. This will help us to make sure that your changes are aligned with the project goals and that you are not duplicating work that is already in progress.

If you are not sure whether your changes are needed, feel free to create an issue anyway and we can discuss it there. Once we have agreed on the changes, you can start working on them.

To keep reviews fast and changes reliable, we have a few non-negotiable guidelines.

Core Rules (Please read this before contributing)

1) One PR = One Issue

• One PR should address exactly one issue (one bug fix, one feature, one refactor goal).
• Don’t bundle unrelated fixes “while you’re in there”.
• If you notice other problems, open separate issues/PRs.

2) Keep PRs Small (Size Limits)

Hard limit: < 500 lines changed (added + removed)
Preferred: < 200 lines changed

📏 Size guidelines

• ~200 lines changed is the sweet spot.
• Up to ~400 lines is acceptable only if the change is:
  • well-scoped
  • self-contained
  • easy to reason about
• Ideally touch fewer than 5 files, unless:
  • the change is repetitive/mechanical (e.g. renaming a prop across components)

If your change is bigger than this, split it into smaller PRs (even if they land sequentially).

3) Must Pass All Tests

Your PR must pass all tests and checks before review/merge.

• Run the full test suite locally when possible.
• If the repo has lint/typecheck steps, they must pass too.
• If tests don’t exist for the area you changed, add them (or clearly explain why testing isn’t feasible and what manual verification you did).

4) Video Walkthrough Required (Every PR)

Include a short Loom video for every PR (UI, backend, refactor, infra—everything).

📺 Video requirements

• 2–3 minutes max
• For bug fixes: show before → after
• Narrate what you changed and why
• Paste the Loom link in the PR description

Examples of good PR videos:

• RoamJS/query-builder#265

5) CodeRabbit Review (Required Before Tagging for Review)

Before requesting human review:

• Trigger CodeRabbit by commenting on the PR:

@coderabbitai full review

• Wait for the review to complete.
• Address all actionable comments.
• Ensure CI passes again after fixes.

If large/significant changes were made, repeat with

@coderabbitai review

What Makes a PR Reviewable

✅ Functionality

Before opening a PR:

• Manually test the feature end-to-end
• Consider edge cases and alternate flows
• Ensure errors are handled and logged gracefully (where applicable)

✅ Scope & Clarity

Your PR description should clearly answer:

• What was broken / missing?
• What did you change?
• How did you verify it works? (tests + manual steps)
• What is the expected behavior now?

If the change or validation is unclear, the PR will be closed or returned for revision.

PRs That Will Be Closed Without Review

We may close PRs (without detailed review) if they:

• try to fix multiple unrelated issues at once
• exceed size limits without a strong reason and clear breakdown
• don’t pass tests / don’t run CI cleanly
• don’t include a Loom video
• don’t clearly show what behavior changed or how it was verified

Requesting Review

Once your PR:

• Addresses exactly one issue
• Is within the size limits
• Passes all tests and CI checks
• Includes the required Loom video
• Clearly explains what changed and how it was verified

👉 Tag @mdroidian in a comment or request them as a reviewer.

Only tag for review after all requirements above are completed.