Skip to content

Latest commit

 

History

History
230 lines (171 loc) · 8.64 KB

CONTRIBUTING.adoc

File metadata and controls

230 lines (171 loc) · 8.64 KB
Raw

Contributing to the Neo4j Ecosystem

At Neo4j, we develop our software in the open at GitHub. This provides transparency for you, our users, and allows you to fork the software to make your own additions and enhancements. We also provide areas specifically for community contributions, in particular the neo4j-contrib space.

There’s an active Neo4j Online Community where we work directly with the community. If you’re not already a member, sign up!

We love our community and wouldn’t be where we are without you. Please remember: Many things are contributions, among them issues, code, documentation and examples.

Building and compiling the Neo4j-Cypher-DSL

Requirements

For the full project, including examples and native tests:

Note
 At least GraalVM 22.3.0 is required due to restrictions in org.graalvm.buildtools:native-maven-plugin. The rationale behind that is explained here and we don’t do apply any of the suggested workarounds as the releases are done with GraalVM 22.3.0 anyway.

For the project, including examples but skipping native tests

Maven 3.8.4 is our build tool of choice. We provide the Maven wrapper, see mvnw respectively mvnw.cmd in the project root; the wrapper downloads the appropriate Maven version automatically.

The build requires a local copy of the project:

Clone the Neo4j Cypher-DSL
$ git clone [email protected]:neo4j-contrib/cypher-dsl.git

Fast build

Note
 This is useful if you want to just have an installation of a snapshot version. No tests are run, no verification is done.
Fast build (only compiling and producing packages)
$ ./mvnw -Dfast package

For a local install - maybe to try out a future release - you can also specify the version number:

Fast build (locally installed, with an artificial version number)
$ ./mvnw -Dfast -Drevision=1337 -Dchangelist= install

Full build (including examples and native tests)

Before you proceed, verify your locally installed JDK version. The output should be similar:

Verify your JDK
$ java -version
openjdk version "17.0.5" 2022-10-18
OpenJDK Runtime Environment GraalVM CE 22.3.0 (build 17.0.5+8-jvmci-22.3-b08)
OpenJDK 64-Bit Server VM GraalVM CE 22.3.0 (build 17.0.5+8-jvmci-22.3-b08, mixed mode, sharing)

Check whether GraalVM native-image is present with:

Check for the present of native-image
$ gu list
ComponentId              Version             Component name                Stability                     Origin
-------------------------------------------------------------------------------------------------------------------
graalvm                  22.3.0              GraalVM Core                  Experimental
js                       22.3.0              Graal.js                      Experimental                  github.com
native-image             22.3.0              Native Image                  Experimental                  github.com

You should see native-image in the list. If not, install it via gu install native-image.

After that, use ./mvnw on a Unix-like operating system to build the Cypher-DSL:

Build with default settings on Linux / macOS
$ ./mvnw clean verify

On a Windows machine, use

Build with default settings on Windows
$ mvnw.cmd clean verify

Skipping native tests

On a plain JDK 17 or higher, run the following to skip the native tests:

Skipping native tests
$ ./mvnw clean verify -pl \!org.neo4j:neo4j-cypher-dsl-native-tests

Build only the core module

The core module can be build on plain JDK 17 with:

Build only the core module
$ ./mvnw clean verify -am -pl org.neo4j:neo4j-cypher-dsl

CI-friendly version numbers

We use CI-friendly version numbers, the current build will always identify itself as 9999-SNAPSHOT. If you need to create a specific version you can specify the revision, the changelist and an optional hash like this:

Specifying revision and changelist
$ ./mvnw clean package -pl org.neo4j:neo4j-cypher-dsl -Drevision=2022.1.0 -Dchangelist=-SNAPSHOT

Releasing (Only relevant for the current maintainers)

Prepare a release with:

./mvnw exec:exec@prepare-release -pl :neo4j-cypher-dsl-parent -Drevision=2020.0.1 -Dchangelist= -Dcypher-dsl.version.next=2020.0.2-SNAPSHOT

and then let do Teamcity the rest, but chose the same version number there, too.

General considerations

Need to raise an issue?

Where you raise an issue depends largely on the nature of the problem.

Firstly, if you are an Enterprise customer, you might want to head over to our Customer Support Portal.

There are plenty of public channels available too, though. If you simply want to get started or have a question on how to use a particular feature, ask a question in Neo4j Online Community. If you think you might have hit a bug in our software (it happens occasionally!) or you have specific feature request then use the issue feature on the relevant GitHub repository. Check first though as someone else may have already raised something similar.

StackOverflow also hosts a ton of questions and might already have a discussion around your problem. Make sure you have a look there too.

Include as much information as you can in any request you make:

  • Which versions of our products are you using?

  • Which language (and which version of that language) are you developing with?

  • What operating system are you on?

  • Are you working with a cluster or on a single machine?

  • What code are you running?

  • What errors are you seeing?

  • What solutions have you tried already?

Want to contribute?

It’s easier for all of us if you try to follow these steps before creating a pull request:

  • Do all your work in a personal fork of the original repository

  • Rebase, don’t merge (we prefer to keep our history clean)

  • Create a branch (with a useful name) for your contribution

  • Make sure you’re familiar with the appropriate coding style (this varies by language so ask if you’re in doubt)

  • Include unit tests if appropriate (obviously not necessary for documentation changes)

Note
 Small things that doesn’t change the public API or documented behaviour and of course bug fixes usually go in quickly. If you want to add new features with public API changes or additions or want to customize or change a feature, please do reach out to us on one of the available channels, preferable by creating a new issue first in which we can discuss the proposed changes.

We can’t guarantee that we’ll accept pull requests and may ask you to make some changes before they go in. Occasionally, we might also have logistical, commercial, or legal reasons why we can’t accept your work, but we’ll try to find an alternative way for you to contribute in that case. Remember that many community members have become regular contributors and some are now even Neo employees!

Further reading

If you want to find out more about how you can contribute, head over to our website for more information.

Got an idea for a new project?

If you have an idea for a new tool or library, start by talking to other people in the community. Chances are that someone has a similar idea or may have already started working on it. The best software comes from getting like minds together to solve a problem. And we’ll do our best to help you promote and co-ordinate your Neo ecosystem projects.