formatting.txt

Code formatting
===============

Starting with (LUCENE-9564) Java code is enforced to comply with
google-java-format conventions. In theory, you shouldn't worry about
what the convention actually looks like - write the code in any way
you like and then run:

./gradlew tidy

prior to running your regular precommit checks. This will reformat
your code so that it complies with the convention and passes gradle
'check' task.

IMPORTANT: wildcard imports are banned but google java format doesn't
detect or fix this. There is a check for wildcard imports implemented
on top of the ast-grep tool (https://ast-grep.github.io/). This tool is
optional. If you'd like to run it locally on gradle's 'check' task,
install ast-grep locally and add this build option to
build-options.local.properties:

lucene.tool.ast-grep=ast-grep

IMPORTANT: There is *no* way to mark sections of the code as excluded
from formatting. This is by design and cannot be altered. In the vast
majority of cases the formatter will do a great job of cleaning up the
code. Occasionally you may want to rewrite the code (introduce a local
variable or reshape code paths) so that it's easier to read after
automatic formatting.


Other file formatting
=====================

CI is configured to run additional linting using eclint
(https://gitlab.com/greut/eclint). This tool is optional. If you'd like
to run it locally on gradle's 'check' task, install eclint locally and add
this build option to build-options.local.properties:

lucene.tool.eclint=eclint

A side effect of enabling eclint is that the 'tidy' task will also attempt
to fix offendling eclint violations (if possible).


Gradle scripts
==============

Groovy and gradle code is also automatically formatted and this formatting
is enforced. This is unfortunately a heavy download and runtime-costly
application. If you'd like to temporarily skip this validation step, set
the lucene.spotlessGradleScripts option to false - either on command line
using -Plucene.spotlessGradleScripts=false, in your local
build-options.local.properties or by any other means build options can be
set.