How to Contribute to Solr

"Contributing" to an Apache project is about more then just writing code – it's about doing what you can to make the project better. There are lots of ways to contribute....

Read CONTRIBUTING.md

The project's git repo has up-to-date contributing information, see CONTRIBUTING.md 

Apart from what is mentioned in that guide, here are some other helpful tips.

Be Involved

Contributors should join the Solr mailing lists. In particular:

• the user list (to help others)
• The commit list (to see changes as they are made)
• The dev list (to join discussions of changes)
• The issues list (to track all JIRA issue changes)

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

Be A Mailing List Moderator

Being a list moderator is incredibly easy - the basic responsibilities are:

• Get a copy of any email sent to one of the Solr lists from an address that is not subscribed and review it to see if it's spam or not
• Occasionally help people with particular difficulties unsubscribing to the mailing list.

If you'd like to volunteer to be the moderator of a mailing list, just contact listname-owner@solr... (ie: users-owner@solr...)

Working with code

Notes for Eclipse

Unit Tests

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

> gradlew clean test

After a while, if you see a success or failure message

Solr testing makes extensive use of randomization. Each test starts with a "seed" for the random number generator, allowing repeatability. We had one test, for instance, that only failed when the locale was set to a particular locale. Re-using the seed reproduces these kinds of cases.

You'll find a "reproduce with..." message either on the screen or in the output that gives the exact command necessary

Carefully read the errors messages and check your code. If the test fails you may want to repeatedly rerun a single test as you debug and sort out any problems. In which case you could run the "reproduce with" command in the output.

Frequently failing Tests

There are some tests that fail sometimes on some systems, but run on Jenkins fine. It's always a good idea to be sure you can run the full test suite successfully before you start making code changes. Or keep an un-changed version of the code around to see if your changes are really to blame.

One of the great things about Open Source is so many people run the tests on so many different systems. Occasionally you'll be the lucky person who has the system that wins the prize by having the environment that exposes a new failure mode, see the discussion at SOLR-3846 for an example.

If you do find one of these, here's what you should do:

• If tests continue to fail, ask on the dev list if anyone else has seen the issue. This is the case where having the un-changed code helps. If the tests fail on both the changed and un-changed versions, discuss on the dev list whether the test should be disabled.
• If tests fail with your changes but not on un-altered code, well, you need to understand why. By far the most frequent reason is a bug or unintended side-effect of your code, but occasionally it's a test that needs modification. Again, the dev list is a good place to discuss this.
• Be very cautious about adding anything like @Ignore to a test. This is generally the wrong thing to do unless you get some consensus, and it'll surely generate "spirited debate".
• Of course any effort you want to make towards tracking down the reason a test fails in your particular environment is greatly appreciated!

PR do-s and don't-s

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 git to figure out what's changed and by whom.
• make things public which are not required by end users.
• Combine multiple issues into a single patch, especially if they are unrelated or only loosely related. This is true even if the changes affect the same files. In some rare cases it is warranted, but for the most part it makes it harder for committers to evaluate the patch.

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.)
• try to provide a unit test that shows a bug was indeed fixed or the new functionality truly works
• use the "draft state" for PRs which are work in progress

Getting your contribution merged

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 your patch if you think they're reasonable. Remember that even a patch/PR that is not committed is useful to the community. Supply your contribution as early as possible, and updates as often as possible during your work. This helps the rest of the community and committers to start understanding, help shaping, commenting on etc. your work throughout the entire process. Supplying a PR does not necessarily mean that it is complete and ready to be committed, it might also just be a way of communicating your idea and progress. It can be usedul to set the PR to "Draft" status until you feel it is ready for broad review.

Commit process using Git

For committers Only committers can put the code in the Git repository.

See Git commit process for the current recommendations (outdated).

JIRA tips (our issue/bug tracker)

The issue tracker we use is a JIRA instance at https://issues.apache.org/jira/browse/SOLR. If you don't yet have an account, you have to ask for one in the 'users' or 'dev' mailing list (se above).

• If you aren't sure if something is a bug, please ask on the solr-user mailing list before opening an issue.
• We do not use JIRA for support or asking questions. If you have a question, please use the users mailing list.
• When creating new issues in JIRA, please keep the "Description" field short - every change or followup on the issue will cause an email to be sent to the solr-dev mailing list, and will include the complete Description every time.
• When attaching newer versions of a file/patch, use the same name... JIRA will "gray out" the older versions automatically.
• Please do not delete older files that you have already added - the complete history of an issue is important.
• The "Activity" section of an issue by default only lists "Comments". If you click on the "All" subtab you can see all activity related to this issue, including any edits that might have been made to the summary or description, as well as an commits that mention this issue in the commit log.

IDE integration

Both Intellij and Eclipse are supported out of the box.

For Lucene/Solr 9x and later, executing "gradlew tasks" will list a section "IDE tasks" to get you started. The dev user's list or the slack solr-dev channel are good places for detailed questions.

Getting your feet wet: where to begin?

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

The Solr developers use the "newdev" label to mark issues that developers new to Solr 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 issues with the newdev label, look at this link https://s.apache.org/newdevsolr

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.

Generated files

There are several files that are generated, for instance several of the tokenizers implement a scanner that is defined in a ".jflex" file. It is rarely necessary to modify the ".jflex" file and almost always a mistake to hand-edit the ".java" file generated from it. If you see any message at the top of a file you're working with like "/* The following code was generated by JFlex 1.7.0 */" please discuss why you want to change it on the development list before proceeding.

One final note

As always, there are gremlins out there. If you find problems with the information here, and especially if you subsequently find solutions to the problems you find, please either write to the solr-user mailing list or update this page directly so others can benefit.