33.5. Contributing Code to Neo4j

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 criterias of contribution and adheres to the community’s Code of Conduct.

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 Contributor 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 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.
  4. Write code.
  5. Write appropriate Javadocs and Manual entries.
  6. Commit changes.
  7. Send pull request.

Pull request checklist

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 validate.

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, preferrably just one line, like calling a method ]

    // Then
    [ Assertions on the result ]
}

Code Style

The Neo4j Code style is maintained on GitHub in styles for the different IDEs.

Commit messages

Please take some care in providing good commit messages. Use your common sense. In particular:

  • 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 Contributor 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, eg. 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.

Single commit

If you have multiple commits, you should squash them into a single one for the pull request, unless there is some extraordinary reason not to. Keeping your changes in a single commit makes the commit history easier to read, it also makes it easy to revert and move features around.

One way to do this is to, while standing on your local branch with your changes, create a new branch and then interactively rebase your commits into a single one.

Interactive rebasing with Git 

# On branch mychanges
git checkout -b mychanges-clean

# Assuming you have 4 commits, rebase the last four commits interactively:
git rebase -i HEAD~4

# In the dialog git gives you, keep your first commit, and squash all others into it.
# Then reword the commit description to accurately depict what your commit does.
# If applicable, include any issue numbers like so: #760

For more details, see the git manual: http://git-scm.com/book/en/Git-Tools-Rewriting-History#Changing-Multiple-Commit-Messages

If you are asked to modify parts of your code, work in your original branch (the one with multiple commits), and follow the above process to create a fixed single commit.