Skip to content

Latest commit

 

History

History
184 lines (137 loc) · 5.89 KB

CONTRIBUTING.adoc

File metadata and controls

184 lines (137 loc) · 5.89 KB

Contributing

Building and compiling the Neo4j JDBC driver

JDK 17 and Maven is required. Please run to test and package the project:

./mvnw verify

There’s a fast profile that will skip all the tests and validations:

./mvnw -Dfast package

If the cluster integration test is flaky or does not work at all in your build, you can skip it like this without skipping any other integration tests:

./mvnw -DskipClusterIT verify

Tasks

Keep the build descriptor (pom.xml) sorted

./mvnw sortpom:sort

Formatting sources / adding headers

When you add new files, you can run

./mvnw license:format

to add required headers automatically.

We use spring-javaformat to format the source files.

./mvnw spring-javaformat:apply
Tip
 The Spring Developers write: "The source formatter does not fundamentally change your code. For example, it will not change the order of import statements. It is effectively limited to adding or removing whitespace and line feeds." This means the following checkstyle check might still fail. Some common errors:
Static imports, import javax. and java. before others
Static imports are helpful, yes, but when working with 2 builders in the same project (here jOOQ and Cypher-DSL), they can be quite confusing.

There are plugins for Eclipse and IntelliJ IDEA and the Checkstyle settings can be imported as well. We took those "as is" and just disabled the lambda check (requiring even single parameters to have parenthesis).

Public classes do require an author tag. Please add yourself as an @author to the .java files you added or that modified substantially (more than cosmetic changes).

Logging

Neo4j-JDBC logs via Java Util Logging (JUL). A sensible configuration for debugging translated statements could look like this:

handlers=java.util.logging.FileHandler
java.util.logging.FileHandler.level=ALL
java.util.logging.FileHandler.pattern=%h/neo4j-jdbc-%u-%g.log
java.util.logging.FileHandler.formatter=java.util.logging.SimpleFormatter
java.util.logging.SimpleFormatter.format = [%1$tFT%1$tk:%1$tM:%1$tS] %5$s%n

.level=INFO
org.neo4j.jdbc.internal.bolt.internal.NetworkConnection.level=INFO
org.neo4j.jdbc.internal.bolt.BoltMessageExchange.level=OFF
org.neo4j.jdbc.Neo4jStatement.level=FINE

This can be used for example with IntelliJs diagnostics. For that to work, you need to disable class-path isolation in IntelliJ or DataGrip, though.

Benchkit support

Standalone runner (Java 17 required):

./mvnw -Dfast -am -pl benchkit clean package
TEST_NEO4J_HOST=localhost TEST_NEO4J_PASS=verysecret java -jar benchkit/target/neo4j-jdbc-benchkit-6.0.0-SNAPSHOT.jar

Built a Benchkit compliant Docker as follows.

 docker build . -f benchkit/Dockerfile --tag neo4j/neo4j-jdbc-benchkit-backend
 docker run --publish=9000:9000 \
  -e TEST_NEO4J_HOST=host.docker.internal \
  -e TEST_NEO4J_PASS=verysecret neo4j/neo4j-jdbc-benchkit-backend

Pick your poison, in both scenarios the following request should work (assuming you have a Neo4j running on your local machine with the given credentials):

curl -X PUT --location "http://localhost:9000/workload" \
    -H "accept: */*" \
    -H "Content-Type: application/json" \
    -d '{
          "method": "executeQuery",
          "database": "",
          "routing": "write",
          "mode": "sequentialSessions",
          "queries": [
            {
              "text": "UNWIND $titles AS title CREATE (n:Movie {title: title}) RETURN n",
              "parameters": {
                "titles": [
                  "Terminator ",
                  "Terminator 2"
                ]
              }
            },
            {
              "text": "UNWIND range(1,10000) AS i CREATE (n:F {i: i}) RETURN n"
            }
          ]
        }'

Conventions

Code

Package private by default, no "impl" packages and the like if avoidable. Public classes must be final unless explicitly designed as SPI.

Commits

Please use conventional commits when possible: Conventional Commits. Two live examples: cypher-dsl and neo4j-migrations.

Building the documentation

The docs are written with AsciiDoctor inside the docs module. The module is build with Maven. The package goal will process all asciidoc files and bundle them up both as generated site and as an Antora-ready zip archive, ready to be included somewhere else.

./mvnw -Dfast clean package -pl docs -am

On JDK21 you can bring up a web-server like this to view the documentation on localhost:8000

jwebserver -d `pwd`/docs/target/generated-docs/

To preview the Antora docs you can run this after the above Maven build succeeds. The Maven build is necessary so that the version numbers and other references in the source files are processed proper:

npm --prefix etc/antora i
npm --prefix etc/antora run preview

The build also provides a zipped version of the Antora module alone, ready to be pushed into another repo under docs/target/jdbc-manual.zip.

Resources