Getting the source code

Lucene's code is versioned with Subversion and available at http://svn.apache.org/repos/asf/lucene/dev/trunk/. To download the source code, just open a terminal and type

svn checkout http://svn.apache.org/repos/asf/lucene/dev/trunk/ lucene-trunk

Depending on your location, the european mirror might be faster or slower:

svn checkout http://svn.eu.apache.org/repos/asf/lucene/dev/trunk/ lucene-trunk

Compiling the source code

Building Lucene requires that you have Apache Ant and Apache Ivy installed. If you have only installed Ant, you can install Ivy by running

ant ivy-bootstrap

You can then run tests by running ant test or compile and create jars by running ant jar. Run ant -p to see the available targets.

Problems with Ivy

Some people have reported problems getting Ivy to work when installed in ${user.home}/.ant/lib

The majority of these issues seem to be people using installations of ant packaged by linux disto providers that either do not provide a full ant install (ie: additional RPMs are required) or explicitly disable the ability to use "user lib" feature of ant in their configs, or have some other problems.

Suggested fixes for people who still have problems getting Ivy to work after running "ant ivy-bootstrap":

  • try using the "--noconfig" option when running ant
  • try adding "rpm_mode=false" to your ~/.ant/ant.conf
  • try removing "rpm_mode=true" from your /etc/ant.conf
  • try installing a clean version of Apache Ant downloaded directly from the Apache mirrors

For more details:

Configuring IDEs

Making changes

Before you start, send a message to the developer mailing list (Note: you have to subscribe before you can post), or file a bug report in Jira. Describe your proposed changes and check that they fit in with what others are doing and have planned for the project. Be patient, it may take folks a while to understand your requirements.

Modify the source code and add some (very) nice features using your favorite IDE.

But take care about the following points:

  • Code compatibility:
    • All code to be included in 3.X releases should be compatible with Java 5.
    • All code to be included in trunk, from which 4.0 will be released, should be compatible with Java 6.
  • All public classes and methods should have informative Javadoc comments.
  • Code should be formatted according to Sun's conventions with one exception:
    • Indent two spaces per level, not four.
  • Contributions should pass existing unit tests.
  • New unit tests should be provided to demonstrate bugs and fixes (http://www.junit.org).
  • The java source code is in the directory lucene/${module}/src/java and the java test code is in the directory lucene/${module}/src/test.

Unit tests

Please make sure that all unit tests succeed before constructing your patch.

To run your test case from ant use the following from the lucene/ directory in your working copy:

ant -Dtestcase=NameOfYourUnitTest test-core

In case your contribution fixes a bug, try and make your test case fail to show the presence of the bug. A test case showing the presence of a bug is also a good contribution by itself.

Once your test case passes, please make sure that all unit tests (core, contrib, back-compatibility, and Solr tests) succeed before constructing your patch, by running this from the lucene/ directory in your working copy:

ant clean test

After a while, if you see

BUILD SUCCESSFUL

all is ok, but if you see

BUILD FAILED

please, read carefully the errors messages and check your code.

Since running all test cases can take some time, after any change try running a previously failing single test case first.

Precommit check

Before constructing your patch, please run the top-level pre-commit check, which finds problems like tabs and @author tags in source files, broken links in javadocs, files not controlled by Subversion (a.k.a. "unversioned files"), etc.

To run the pre-commit checks from ant, run the following from the top-level directory – the directory containing lucene/ and solr/ – in your working copy:

ant precommit

Creating a patch

Check to see what files you have modified with:

svn stat

Add any new files with:

svn add src/.../MyNewClass.java

Edit the CHANGES.txt file, adding a description of your change, including the bug number it fixes.

In order to create a patch, just type:

svn diff > LUCENE-NNNN.patch

This will report all modifications done on Lucene sources on your local disk and save them into the LUCENE-NNNN.patch file. Read the patch file. Make sure it includes ONLY the modifications required to fix a single issue.

Note the LUCENE-NNNN.patch patch file name. Please use this naming pattern when creating patches for uploading to JIRA. Once you create a new JIRA issue, note its name and use that name when naming your patch file. For example, if you are creating a patch for a JIRA issue named LUCENE-3456, then name your patch filename LUCENE-3456.patch. If you are creating a new version of an existing patch, use the existing patch's file name. JIRA will automatically "gray out" the old patch and clearly mark your newly uploaded patch as the latest.

Please do not:

  • Reformat code unrelated to the bug being fixed: formatting changes should be separate patches/commits.
  • Comment out code that is now obsolete: just remove it.
  • Insert comments around each change, marking the change: folks can use subversion to figure out what's changed and by whom.
  • Make things public which are not required by end users.
  • Add @author tags to your code. (Instead, give yourself credit in the CHANGES.txt file.)

Please do:

  • Try to adhere to the coding style of files you edit;
  • Comment code whose function or rationale is not obvious;
  • Update documentation (e.g., package.html files, this wiki, etc.)

Contributing your work

Finally, patches should be attached to a bug report in Jira.

Please be patient. Committers are busy people too. If no one responds to your patch after a few days, please make friendly reminders. Please incorporate others' suggestions into into your patch if you think they're reasonable. Finally, remember that even a patch that is not committed is useful to the community.

Stay involved

Contributors should join the Lucene mailing lists. In particular, the commit list (to see changes as they are made), the dev list (to join discussions of changes) and the user list (to help others).

Please keep discussions about Lucene on list so that everyone benefits. Emailing individual committers with questions about specific Lucene issues is discouraged. See http://people.apache.org/~hossman/#private_q.

Getting your feet wet: where to begin?

New to Lucene? Want to find JIRA issues that you can work on without taking on the whole world?

The Lucene/Solr developers use the "newdev" label to mark issues that developers new to Lucene might be interested in working on. The rough criteria used to make this selection are:

Nobody has done any work on the issue yet.
The issue is likely not controversial.
The issue is likely self-contained with limited scope.
To see a list of open Lucene and Solr issues with the newdev label, use the JIRA query (project=SOLR OR project=LUCENE) AND (status=OPEN OR status=REOPENED) AND labels=newdev

Note: Fixing these issues may require asking questions on the developer list to figure out what they mean - there is no guarantee that any of these will be either quick or easy.

  • No labels