dev-docs/FAQ.adoc - solr - Git at Google

 = Frequently Asked Questions
 :toc: left


 == 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 xref:running-in-docker.adoc[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 -noprompt` 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 https://google.github.io/styleguide/javaguide.html[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:

  * https://github.com/google/google-java-format#eclipse
  * https://plugins.jetbrains.com/plugin/8527-google-java-format

 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.

 https://errorprone.info/[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 https://lift.sonatype.com/[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 https://github.com/policeman-tools/forbidden-apis[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 https://plugins.gradle.org/plugin/org.owasp.dependencycheck[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 users@solr.apache.org mailing list before opening an issue.
 1. We do not use JIRA for support or asking questions. If you have a question, please use the users mailing list.
 1. 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 dev@solr.apache.org mailing list, and will include the complete Description every time.
 1. When attaching newer versions of a file/patch, use the same name... JIRA will "gray out" the older versions automatically.
 1. Please do not delete older files that you have already added - the complete history of an issue is important.
 1. 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.
 1. 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.

 === Where can I find information about test history?

 * http://fucit.org/solr-jenkins-reports/failure-report.html
 * https://ge.apache.org/scans/tests?search.relativeStartTime=P90D&search.rootProjectNames=solr*
 * https://lists.apache.org[Solr mailing list archives especially builds]
	= Frequently Asked Questions
	:toc: left


	== 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 xref:running-in-docker.adoc[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 -noprompt` 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 https://google.github.io/styleguide/javaguide.html[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:

	* https://github.com/google/google-java-format#eclipse
	* https://plugins.jetbrains.com/plugin/8527-google-java-format

	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.

	https://errorprone.info/[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 https://lift.sonatype.com/[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 https://github.com/policeman-tools/forbidden-apis[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 https://plugins.gradle.org/plugin/org.owasp.dependencycheck[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 users@solr.apache.org mailing list before opening an issue.
	1. We do not use JIRA for support or asking questions. If you have a question, please use the users mailing list.
	1. 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 dev@solr.apache.org mailing list, and will include the complete Description every time.
	1. When attaching newer versions of a file/patch, use the same name... JIRA will "gray out" the older versions automatically.
	1. Please do not delete older files that you have already added - the complete history of an issue is important.
	1. 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.
	1. 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.

	=== Where can I find information about test history?

	* http://fucit.org/solr-jenkins-reports/failure-report.html
	* https://ge.apache.org/scans/tests?search.relativeStartTime=P90D&search.rootProjectNames=solr*
	* https://lists.apache.org[Solr mailing list archives especially builds]