Skip to main content
Apache Lucene welcomes bug fixes, improvements, and new features. This guide walks through everything you need to go from zero to an open pull request.

​
Getting the source code

Clone the repository from GitHub: 
git clone https://github.com/apache/lucene
On Windows, preserve the original line endings when cloning. Some files have their checksums verified during the build and will fail if line endings are altered.

​
Prerequisites

1

Install JDK 25

Lucene 11.0 requires JDK 25 as the minimum Java version. You can obtain it from any of the following providers:Confirm your version before proceeding:
java -version
2

Install Perl and Python 3

Some build tasks — in particular ./gradlew check — require Perl and Python 3. Install them using your system’s package manager if they are not already present.
# Example on Debian/Ubuntu
sudo apt install perl python3
3

Verify the Gradle wrapper

You do not need to install Gradle manually. The project ships a Gradle wrapper (gradlew / gradlew.bat) that downloads the correct version automatically.
Do not use a system-installed gradle command. This can result in using a different Gradle version than the project requires, which causes cryptic build errors.

​
Building with Gradle

The Gradle wrapper handles everything needed to build the project from scratch. On first run it creates a gradle.properties file with machine-specific settings that can be left as-is in most cases. To see a summary of typical workflow tasks: 
./gradlew helpWorkflow
For a full list of help guides covering the build system: 
./gradlew help

​
Code formatting

Lucene enforces google-java-format conventions for all Java source files. After modifying source files, run: 
./gradlew tidy
This rewrites your code to comply with the formatting convention automatically.
Wildcard imports are banned but google-java-format does not detect or fix them. The pre-commit check (uvx prek) will catch them. See Pre-commit validation below.
For more details on formatting rules, run: 
./gradlew helpFormatting

​
Running tests

This is the command to run before submitting a contribution. It assembles Lucene and runs all validation tasks, including tests:
./gradlew check
To run validations but skip tests:
./gradlew check -x test
Use the -p flag to target a module by its directory path:
./gradlew -p lucene/core test
Or use the full Gradle project path:
./gradlew :lucene:core:test

./gradlew -p lucene/core test --tests TestDemo
./gradlew -p lucene/core test --tests "*testFeatureMissing*"

./gradlew -p lucene/core test -Ptests.verbose=true --tests TestDemo
Lucene tests use randomization. To reproduce a failure, pass the seed reported in the failing test:
./gradlew -p lucene/core test -Ptests.seed=DEADBEEF
For the full list of test options and filtering: 
./gradlew helpTest

​
Pre-commit validation

Lucene uses prek for fast pre-commit checks. It lints Markdown files, Python scripts, shell scripts, and more. Run checks on staged changes: 
uvx prek
Install as a git pre-commit hook so checks run automatically before every commit: 
uv tool install prek
prek install --allow-missing-config
The --allow-missing-config option is required if you also work on older release branches that do not yet support prek.
Force-check all files (as CI does): 
uvx prek --all-files
You need the uv package manager to run prek.

​
Writing tests for bug fixes

When fixing a bug, write a new test case that fails before your fix and passes after. A failing test that demonstrates a bug is a valid contribution on its own.
Lucene uses the randomizedtesting framework. Place test classes alongside the source they exercise, following the existing naming conventions in the module you are working in.

​
Creating a patch or pull request

​
Opening a pull request

Open your pull request against the main branch on github.com/apache/lucene. Committers will backport accepted changes to maintenance branches where applicable.
1

Fork and branch

Fork the repository on GitHub and create a feature branch from main.
2

Make your changes

Apply your fix or feature. Run ./gradlew tidy to format code and ./gradlew check to verify everything passes.
3

Add a CHANGES entry

Add an entry to lucene/CHANGES.txt. Format it as:
* GITHUB#XXX: Description of the change. (Your Name)
Where XXX is the issue or pull request number.
4

Open the pull request

Push your branch and open a PR on GitHub. Refer to GitHub’s pull request documentation if needed.

​
Creating a patch (alternative)

If you prefer to attach a patch to an issue rather than opening a PR:
  1. Keep your main branch up to date with upstream: git pull.
  2. Generate a patch with git diff or git format-patch.
  3. Rename the file from XXX.patch to XXX.patch.txt — GitHub does not accept .patch attachments directly.
  4. Attach the file to the relevant GitHub issue.
You do not need to create a patch if you have already opened a pull request.

​
IDE support

Import the project as a Gradle project — it should work out of the box.For faster test execution, configure IntelliJ to use its own built-in test runner: navigate to File → Settings → Build, Execution, Deployment → Build Tools → Gradle and set both “Build and run using” and “Run tests using” to IntelliJ IDEA.Note: some tests are designed to run only via the Gradle wrapper and will not work under the built-in runner.
Generate Eclipse project files:
./gradlew eclipse
Then import the project with File → Import → Existing Project into Workspace.Note: Eclipse does not distinguish between sub-projects and source sets, so all sources and dependencies appear in one combined view.
Generate the Eclipse-compatible project files (VSCode uses the same setup):
./gradlew eclipse
Then open the Lucene checkout directory in VSCode.

​
Staying involved

Contributors should join the Lucene mailing lists:
  • Users list (java-user@lucene.apache.org) — get help and help others.
  • Developers list (dev@lucene.apache.org) — discuss design and upcoming changes.
  • Commits list (commits@lucene.apache.org) — see changes as they land.
Keep discussions on the list so everyone benefits. Emailing individual committers about specific issues is discouraged.
For more contribution guidelines and tips, see the Lucene Developer Tips wiki.

​
Finding a first issue

New contributors looking for a good starting point should look for issues that:
  • Have not had any work done yet.
  • Are unlikely to be controversial.
  • Are self-contained with limited scope.
Search the GitHub issue tracker for issues tagged good first issue or help wanted.

Build docs developers (and LLMs) love

Get started for freeTalk to us