Contributing Code

Intro

The Neo4j community is a free software and open source community centered around software and components for the Neo4j Graph Database. It is sponsored by Neo Technology, which provides infrastructure (different kinds of hosting, documentation, etc.) as well as people to manage it. The Neo4j community is an open community, in so far as it welcomes any member that accepts the basic criteria of contribution.

Contribution can be in many forms (documentation, discussions, bug reports). This document outlines the rules of governance for a contributor of code.

Governance Fundamentals

In a nutshell, you need to be aware of the following fundamentals if you wish to contribute code:

  • All software published by the Neo4j project must have been contributed under the Neo4j Code Contributors License Agreement.

  • Neo4j is a free software and open source community. As a contributor, you are free to place your work under any license that has been approved by either the Free Software Foundation or the Open Source Initiative. You still retain copyright, so in addition to that license you can of course release your work under any other license (for example a fully proprietary license), just not on the Neo4j infrastructure.

  • The Neo4j software is split into components. A Git repository holds either a single or multiple components.

  • The source code should follow the Neo4j Code Style and "fit in" with the Neo4j infrastructure as much as is reasonable for the specific component.

Contributor Roles

Every individual that contributes code does so in the context of a role (a single individual can have multiple roles). The role defines their responsibilities and privileges:

  • A patch submitter is a person who wishes to contribute a patch to an existing component. See Contribution Workflow below.

  • A committer can contribute code directly to one or more components.

  • A component maintainer is in charge of a specific component. They can:

    • commit code in their component’s repository,

    • manage tickets for the repository,

    • grant push rights to the repository.

  • A Neo4j admin manages the Neo4j infrastructure. They:

    • define new components and assign component maintainership,

    • drive, mentor and coach Neo4j component development.

Contribution Workflow

Code contributions to Neo4j are normally done via Github Pull Requests, following the workflow shown below. Please check the Pull Request Checklist before sending off a pull request as well.

  1. Fork the appropriate GitHub repository.

  2. Create a new branch for your specific feature or fix.

  3. Write unit tests for your code, even for small contributions.

  4. Write code.

  5. Write appropriate Javadocs and entries in the Neo4j Manual.

  6. Commit changes.

  7. Send pull request.

Pull Request Checklist

  1. Sign the CLA.

  2. Ensure that you have not added any merge commits.

  3. Rebase against the latest master.

  4. Run all relevant tests.

  5. Send the request!

Unit Tests

You have a much higher chance of getting your changes accepted if you supply us with small, readable unit tests covering the code you’ve written. Also, make sure your code doesn’t break any existing tests. Note that there may be downstream components that need to be tested as well, depending on what you change.

To run tests, use Maven rather than your IDE to ensure others can replicate your test run. The command for running Neo4j tests in any given component is mvn clean test.

The general structure of a unit test looks like this:

@Test
public void myTest()
{
    // Given
    [ Setup code here, setting the stage and
      parameters that are relevant ]

    // When
    [ The code that is being tested, preferably
      just one line, like calling a method ]

    // Then
    [ Assertions on the result ]
}

Code Style

The Neo4j Code style is maintained at http://neo4j.github.io/.

Commit Messages

Please take some care in providing good commit messages; an excellent summary of good practices can be found at http://chris.beams.io/posts/git-commit/. Please also consider the following guidelines:

  • Use english. This includes proper punctuation and correct spelling. Commit messages are supposed to convey some information at a glance — they’re not a chat room.

  • Remember that a commit is a changeset, which describes a cohesive set of changes across potentially many files. Try to group every commit as a logical change. Explain what it changes. If you have to redo work, you might want to clean up your commit log before doing a pull request.

  • If you fix a bug or an issue that’s related to a ticket, then refer to the ticket in the message. For example, "Added this and then changed that. This fixes #14." Just mentioning #xxx in the commit will connect it to the GitHub issue with that number, see GitHub issues. Any of these synonyms will also work:

    • fixes #xxx

    • fixed #xxx

    • fix #xxx

    • closes #xxx

    • close #xxx

    • closed #xxx.

  • Remember to convey intent. Don’t be too brief but don’t provide too much detail, either. That’s what git diff is for.

Signing the CLA

One crucial aspect of contributing is the Contributors License Agreement. In short: make sure to sign the CLA, or the Neo4j project won’t be able to accept your contribution.

Don’t merge, use rebase instead!

Because we would like each contribution to be contained in a single commit, merge commits are not allowed inside a pull request. Merges are messy, and should only be done when necessary, e.g. when merging a branch into master to remember where the code came from.

If you want to update your development branch to incorporate the latest changes from master, use git rebase. For details on how to use rebase, see Git manual on rebase: the Git Manual.