Skip to content

Latest commit

 

History

History
193 lines (139 loc) · 7.49 KB

CONTRIBUTING.adoc

File metadata and controls

193 lines (139 loc) · 7.49 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 Neo4j-Migrations

Warning
 As of writing a loose list of how things needs to be run, not exhaustive.

Producing native binaries

Note
 Native binaries for Windows, Unix and macOS are supplied since 0.3.1 at the releases page.
Warning
 The natively compiled version does not support Java-based migrations and will fail if you try to point it to any package to scan.

The Neo4j Java driver and this application supports native compilation with GraalVM so that you can create a native executable. Read more about it here.

After installing at least GraalVM 21.3.0 based on JDK 17, prepare your environment as follows:

export GRAALVM_HOME=/Library/Java/JavaVirtualMachines/graalvm-ce-java17-21.3.0/Contents/Home
export JAVA_HOME=$GRAALVM_HOME

The paths are probably different on your system.

The neo4j-migrations-cli module has a build profile create-native-image that you use to create a binary for your OS. Run it with:

./mvnw -Dnative clean package

The resulting migration tool can only be used to load Cypher script based migrations in file locations. It won’t find classes, as those are instantiated dynamically via reflection, which is not supported in full in a native image.

Note
 You can try to use upx to compress your binaries. While it has some downsides on the RSS memory usage as explained by the folks over at the Quarkus team, the advantages of having a 2/3 smaller binary are bigger.
If you want to enable the compression in your build, add -DskipCompress=false to the build.

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

Releasing (Only relevant for the current maintainers)

Releases will be created via standard Maven release:prepare / release:perform cycle.

./mvnw release:prepare
./mvnw release:perform

Bumping minor or major versions

Use the provided script to bump the minor or major version:

./bin/bump-version.sh 3.0

Version can be either a new major or minor version (such as 3, 3.0 etc.) or a fully qualified snapshot version (such as 3.0.0-SNAPSHOT).

Building the documentation

The documentation consists of three components:

  • Javadoc (API documentation generated by Maven)

  • Project info (generated by Maven)

  • User documentation (generated by Antora)

You can use the following command to build both the Javadoc and the project info site using Maven:

./mvnw compile site:site site:stage

To generate the user documentation, you need to install Node.js. Once you’ve installed Node.js, it’s time to install the project dependencies using: npm i --prefix etc/antora.

You can now use the following command to build the user documentation:

npm run build-local --prefix etc/antora

You should get the following output:

> neo4j-migrations-docs@1.0.0 build-local
> antora local-antora-playbook.yml

Site generation complete!
Open file:///path/to/neo4j-migrations/target/antora/index.html in a browser to view your site

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.