jabref-contributor

name	jabref-contributor
category	developers
description	Gradle build, module layout (jablib, jabgui, jabkit, jabls, jabsrv), JUnit 5 testing rules, naming conventions, and the mandatory pre-PR checklist for contributing to JabRef.
license	MIT

Contributing to JabRef

Conventions for working on the JabRef codebase.

AI policy — read first. JabRef does not accept fully AI-generated pull requests. AI tools may only assist; a human must understand and take responsibility for every change. See CONTRIBUTING.md and AGENTS.md in the repository root — when working in a JabRef checkout, read both files before making changes.

Modules

Module	Purpose
jablib	Core library — logic, model, importers/exporters
jabgui	JavaFX desktop GUI
jabkit	CLI application
jabls	Language Server Protocol implementation
jabsrv	HTTP server

Key paths: jablib/src/main/java/org/jabref/logic/ (business logic), jablib/src/main/java/org/jabref/model/ (data model), jabgui/src/main/java/org/jabref/gui/ (GUI), docs/ (developer docs and ADRs).

Build and run

Requires JDK 25+ for Gradle (the wrapper downloads a JDK itself):

./gradlew build            # build all modules
./gradlew :jabgui:run      # launch the GUI
./gradlew :jablib:test     # run core tests

Conventions

• Terminology: say "library", not "database" — prefer Library* over Database* in new identifiers (see the glossary, in particular library).
• Tests: plain JUnit 5 assertions only (see ADR-0009); do not introduce Hamcrest or AssertJ. Mock *Preferences classes and stub only the getters the test needs.
• Minimal diffs: no reformatting of existing code, no speculative refactoring, no drive-by cleanups.
• Dependencies: do not add new ones without justification.
• Architecture decisions: documented as ADRs in docs/decisions/; add a new ADR when making an architecturally significant choice.
• Localization: user-visible strings go through Localization.lang(...); add keys to jablib/src/main/resources/l10n/JabRef_en.properties only — other languages are translated via Crowdin.

Before opening a PR

Work through every point of CHECKLIST.md in the repository root — it is the mandatory quality gate. Also:

• Add a CHANGELOG.md entry (unreleased section) for user-visible changes.
• Reference the issue the PR fixes.
• Run ./gradlew rewriteRun if the build reports OpenRewrite violations.

Further reading

• AGENTS.md — rules for automated agents in this repository
• CONTRIBUTING.md — full contribution guide, including the AI usage policy
• CHECKLIST.md — the mandatory pre-PR quality gate
• https://devdocs.jabref.org/ — developer documentation
• https://deepwiki.com/JabRef/jabref — architecture Q&A