...

"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....

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)

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.

...

• Get a copy of any email sent to one of the Lucene 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@lucene... (ie: solr-user-owner@lucene...)

...

• get the source
• edit the reference guide (*.adoc files in ...solr/solr-ref-guide/src)
• raise a JIRA and submit a patch.
  • for very minor changes, spelling errors, grammar corrections and the like it's probably better to just leave a comment on the reference guide page rather than go through the heavyweight process of creating a JIRA and patch.

This means that everyone can help improve the Reference Guide by editing these files and seeing your changes exactly as they will appear. Just like the source code, if your patch is approved a committer will have to pick it up. Some helpful instructions are in ../solr/solr-ref-guide/meta-docs. See particularly asciidoc-syntax.adoc and editing-tools.adoc.

...

• master: Working towards the eventual 9.0 release. This is the main center for development, it's not really a branch. Releases are never made from master, they are only made from the stable development branch.
• branch_8x: The current stable development branch for the next stable 8.x version.
• branch_7x: The previous stable development branch for 7.x releases.
• lucene_solr_7_1: The branch from which 7.1.x versions are built. This is a minor release branch.
• branch_6x: The previous stable development branch for 6.x releases.
• releases/lucene-solr/7.1.0: When a new version is fully released, the branch_x_x branch is copied to a tag which represents the source code for that specific release.
• branch_6_6: When 7.0.0 was released and 6.x went into maintenance mode, all maintenance development moved to this branch, because it was the last minor release branch in the 6.x line. Only fixes for major bugs and security issues are made to versions in maintenance mode.
• branch_5_5: When 6.0.0 was released and 5.x went into maintenance mode, all maintenance development moved to this branch, because it was the last minor release branch in the 5.x line. Normally with the release of 7.0.0 all development would cease on the 5.x code, but a temporary exception was made for this branch because of a security issue, and version 5.5.5 was released *after* the 7.0.0 release to fix that problem.

Every git commit has a SHA hash value. In many cases, this value can be used to obtain specific branches and tags from their parents. For example, the git sha value of df4de29b55369876769bb741d687e47b67ff9613 on branch_6_6 corresponds to the official 6.6.2 release, so if you check out that commit from branch_6_6 you will get exactly the same code as the release tag for 6.6.2. In cases where the release has already been announced, you can also just do a checkout of the release tag, releases/lucene-solr/6.6.2 is an example.

...

Be sure that you are using an appropriate version of the JDK. Current master branch requires Java 11 and branch_8x requires Java 8 (1.8.x).

Working with GitHub

If you prefer you could use the GitHub mirror instead. Note that the drop-down lets you select "master" or "branch_7x" (among others). We accept GitHub Pull Requests (PR). To submit one, first fork the project, then make changes in a feature branch which you push to GitHub and use as the basis for the PR. PRs should be linked to a JIRA issue in the appropriate project here: Solr Jira or here: Lucene Jira. To link your PR to the Jira issue simply include the Jira issue id in the title of the PR (first create the Jira issue if one doesn't exist).

Note about fork permissions: By default, personal fork branches on Github can only be edited by the fork owner.  This prevents others from contributing to your PR.  It's recommended that contributors change the settings on their personal fork, or on specific PR branches to allow these outside edits. The easiest way to do this is involves setting the "Allow edits from maintainers" option described here.

Note about old forks: If you had an existing GitHub fork from before January 23rd 2016, then it will no longer list as "forked from" the official apache/lucene-solr project, meaning that PRs will not go to the Lucene project. Technically this is because the old apache/lucene-solr GitHub repo was deleted and then re-added during the git switch, causing all forks to choose another "parent" project. The only fix for this is to delete your fork on the GitHub website and re-fork from the correct project.

...

• All public classes and methods should have informative Javadoc comments.
• Code should be formatted according to Sun's conventions, with some exceptions:
  • indent two spaces per level, not four.
  • lines can be greater than 80 chars long, 132 is a common limit. Try to be reasonable for very long lines.
• Contributions should pass existing unit tests.
• New unit tests should be provided to demonstrate bugs and fixes (http://www.junit.org).

Notes for Eclipse

To get correct classpath, formatting, encoding, and project settings in Eclipse, simply run ant eclipse and then reload the project in Eclipse. Be sure that you are using an appropriate version of the Java JDK. Solr has required Java 8 (1.8.x) since version 6.0.

...

• First, just try running 'ant -Dtests.badapples=false test'. If the tests succeed, this is a known issue that we haven't found a solution for yet, but want to gather information about. If you have the time, ping the dev list and include your setup details. But in the case where setting this flag causes the tests to succeed, you can assume that your code changes didn't cause this error and go ahead.
• 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 can be annotated as a 'badapples' test or not.
• 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!

Pre-commit 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 Git (a.k.a. "unversioned files"), etc.

...

• 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

Contributing your work

Patches should be attached to a bug report in Jira. If you are revising an existing patch, please re-use the exact same name as the previous attachment. JIRA will automatically "gray out" the old patch and clearly mark your newly uploaded patch file as the latest (it'll be the colored link). You'll see multiple copies of your patch if you've named them identically, and this is preferred as it preserves the history of the patch which can come in handy. Since the most recent one is the only one not gray, we always know which one to use.

...

• NOTE: the "create" button will create a JIRA. Use the button rather than the drop down that says "create service desk request", this latter is a bit confusing.
• 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.
• If you aren't sure if something is a bug, please ask on the solr-user mailing list before opening an issue.
• 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.

...

• Eclipse (Eclipse codestyle).
• IntelliJ (IntelliJ codestyle) NOTE: there is no need to install this file separately if you execute "ant idea", it is done for you. If you do install it, you'll have to tweak the name to select in in IntelliJ as it's currently anonymous (all the more reason to use the ant target, see the IntelliJ instructions).

Solr1.3 If you are using eclipse to follow trunk (leading up to the 1.3 release) eclipse will give several errors about not resolving components in the solrj library. This will appear in the org.apache.solr.handler.component package relating to distributed search (sharedrequest.java ...etc) The solution is to compile the solrj library via the dist-solrj target and add them to your eclipse build path. After running the dist-solrj target look in dist/solrj-lib and add apache-solr-solrj-1.3-dev.jar and commons-httpclient-3.1.jar to your buildpath.

...

• 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 Solr and Lucene issues with the newdev label, look at this link http://s.apache.org/newdevlucenesolr

...

• Check out the most recent jflex branch. This is important since what Lucene uses is based on trunk rather than a released version (thanks for tutoring me Uwe!). Do this by executing: svn co https://jflex.svn.sourceforge.net/svnroot/jflex/trunk jflex
• cd jflex
• mvn install (NOTE: I've seen the tests fail in this step, doesn't seem to matter)
• cd <solr_home>/lucene/analysis/common
• export ANT_OPTS="-Xmx1G -XX:+CMSClassUnloadingEnabled -XX:MaxPermSize=1G" (1)
• ant jflex

(1) I was getting OOM errors when running "ant jflex", and got a tip to do this, which made that problem go away. You may not have to be so generous with memory, but this worked... (Thanks Steve!).

...