29.4. Contributing Code to Neo4j

29.4.1. Intro
29.4.2. The Fast Track
29.4.3. Governance fundamentals
29.4.4. Contributor roles
29.4.5. Code Style
29.4.6. Unit Tests
29.4.7. Workflow
29.4.8. Commit messages

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

29.4.2. The Fast Track

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.

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

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

29.4.5. Code Style

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

29.4.6. Unit Tests

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

29.4.7. Workflow

  • Fork the appropriate repository on GitHub, and clone it.
  • Create a new, appropriately named branch in your local repository for that specific feature or bugfix. Keeping a new branch for each feature ensures we can easily pull in your changes without pulling in any other commits that are not supposed to be pulled.
  • Modify the code to do what you want (e.g. fix a bug, implement a feature).
  • Make sure your changeset has unit tests that are readable and relevant for your change. Try to do this even for small fixes. You never know whether you have introduced some weird bug without testing.
  • Run the Maven build frequently so you know if you’ve introduced any unexpected issues (mvn clean verify). Running tests from your IDE isn’t repeatable enough, even if you run all of the tests in the project.
  • When adding new functionality or changing existing code significantly, be sure to add or update Javadoc comments to non-trivial classes and methods. Also check if the manual is affected by your change and needs to be updated, see Section 29.3, “Writing Neo4j Documentation”.
  • Give each commit an appropriate commit message, so that others who are not familiar with the matter get a good idea of what you have changed.
  • Once you are satisfied with your changes, merge with our upstream repository. We can pull your stuff, but since you know best what you changed, you should do the merge. Use rebase and/or squash commits as appropriate!
  • This is a good point to do one last clean build to see that the merge hasn’t broken your code.
  • Push to your remote repository on GitHub.
  • Send a Pull Request with a description of what you changed via the button in the GitHub interface of your repository. If you know the person responsible for the component, be sure to mention him in the Pull Request (e.g. @user) so he will be notified.

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