Skip to content

Latest commit

 

History

History
103 lines (68 loc) · 5.89 KB

FAQ.adoc

File metadata and controls

103 lines (68 loc) · 5.89 KB
Raw

Frequently Asked Questions

Table of Contents

FAQ

This document provides a quick reference for common developer questions.

What do I do with NOTICE.txt if I don’t have one to satisfy Gradle?

You create an empty file, similar to the /solr/licenses/antlr4-runtime-NOTICE.txt

What are best practices for branches in Git?

Most committers already use a private fork branch for PRs. Use of central branches is ok for very collaborative work, but 95% of the time it is better to use a private branch to avoid extra mailing list traffic etc.

Periodically review https://github.com/apache/solr/branches/all to see if you have created a branch that can be deleted.

How do I run Solr in Docker?

You can review instructions for running Solr in Docker in the Running in Docker developer doc.

Whats the fastest build lifecycle for frontend work on Solr Admin?

Run gradle dev, and then cd ./packaging/build/dev/. Fire up your cluster via bin/solr start -e cloud --no-prompt and then as you make changes to assets in /solr/webapp/web, run gradle dev to redeploy the web assets. Do a hard refresh in your browser to pick up your changes.

Are there Coding Standards to follow?

Please follow the Google Java Style Guide. We don’t follow all aspects strictly; much code was written before this style guide was selected. The whitespace formatting aspect of this guide is mandatory and strictly enforced with tooling. To format the code automatically using "Spotless", do the following:

./gradlew tidy

Learn more via ./gradlew :helpFormatting. Major IDE vendors have plugins for this style guide to help keep your code formatted as you work:

We use a number of tools for ensuring that Solr’s codebase follows our community standards. The most important tool is the very rich testing infrastructure that Solr enjoys. We strive for testing of every aspect of Solr. If you find a bug, write a test demonstrating it, so we can ensure that once the bug is squashed, it stays squashed.

The Eclipse IDE’s linting tool ECJ is applied as part of the check task.

Error Prone goes beyond static type checking and recommends fixes for common bug patterns. Error Prone is run during the CI build on Jenkins, however to run it locally (and skip the tests) do:

./gradlew check -Pvalidation.errorprone=true -x test

In the same space as Errorprone is Sonatype Lift, an automated code reviewer that is run when you push your PR to Github. As with human reviewers, it’s a good practice to respond to each comment to reflect on the recommendation. Of course, automated code analysis will turn up false-positives. Tip: There is no point in responding to Lift with the ignore command because we don’t gate PRs on Lift.

There are Java classes and methods that Solr doesn’t allow. This exclusion is enforced by the Forbidden APIs tool and is applied as part of the check task. Learn more about using Forbidden APIs via ./gradlew :helpForbiddenApis.

To run a check for dependencies of Solr that have security vulnerabilities using the OWASP Gradle plugin. Run via:

./gradlew owasp

There are a number of other tasks that get run to validate the source code, and you can find them in the ./gradle/validation source tree.

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.

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 (see https://solr.apache.org/community.html#mailing-lists-chat).

  1. If you aren’t sure if something is a bug, please ask on the [email protected] mailing list before opening an issue.

  2. We do not use JIRA for support or asking questions. If you have a question, please use the users mailing list.

  3. 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 [email protected] mailing list, and will include the complete Description every time.

  4. When attaching newer versions of a file/patch, use the same name…​ JIRA will "gray out" the older versions automatically.

  5. Please do not delete older files that you have already added - the complete history of an issue is important.

  6. The "Activity" section of an issue by default only lists "Comments". If you click on the "All" sub-tab 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.

  7. Have follow up work to an existing issue that is closed? If an issue is closed, its supposed to remain closed since it has been "shipped" in a release. Create a new issue and link it.

How can I build the JavaDoc’s and the Reference Guide?

Run ./gradlew buildLocalSite to build the Javadoc’s and the Reference Guide site.