Contributing to the Java SDK

We love contributions :smiley: :heart:

:question: Do you have any particular contribution in mind?

We use Gerrit for code reviews. The process is a little bit different from Github’s pull-requests so it’s a little bit more involved, but know that there are improvements on the way (like a bot that attempts to port PRs into Gerrit, or the possibility to login with Github accounts).

Pre-requisites
Basically, right now you need to:

After that, you’ll be meeting the prerequisites to contribute.

Getting Ready to Contribute Code
The wiki page on contributing contains more detailed steps, especially on how to correctly clone and set up a project, so I encourage you to look through it after reading this message.

Michael Nitschinger and I (Simon Baslé) are the reviewers for both couchbase-java-client and couchbase-jvm-core.

The commit messages follow this convention (see history on Github for examples):

JIRA-ISSUE: Short line of desc (52 chars total)

Motivation:
-----------
Paragraph about the motivation behind the change, what was
the problem. Hard line wraps at 70 chars.

Modifications:
--------------
Describe what changed. Hard line wraps at 70 chars.

Results:
--------
How does it impact the user, do tests pass. Hard line wraps at 70
chars.

One thing we’d like to do is tag issues in JIRA that are ideal-for-contribution, but for now there is none identified as such.

A little crash course on Gerrit’s philosophy:

Gerrit is our canonical repository for changes and each time a changeset is reviewed, it is picked into the corresponding branch in Github (so Github is the public repository, with a clean history, while Gerrit keeps track of all the intermediate states of a review).

Gerrit works with changesets, by attributing a Change-Id to a patch the first time it is committed [1]. But unlike Github’s PRs, you don’t add to your changeset by adding more commits to it. You just commit --amend (or squash), making sure that the Change-Id is kept at the end of the commit message, then you push to a special branch [2].

That way, Gerrit will automatically detect that the commit is another iteration on the same changeset (called a patchset). The UI will allow you to review differences between any two patchsets, or the latest+base branch, comment on each patchset, each line of code, etc…

The UI is less sexy than Github’s, but it works and you can enforce good commit history while tracking everything, as well as enforcing submit policies. For instance, we require that a changeset be marked by the author as Verified +1 to indicate that tests were run and ready to review. Then someone from the project’s team must Code-Review +2 to indicate the change is ok to merge. Negative score indicate there are still iterations to perform on the change.

[1] through the use of a Git commit hook
[2] refs/for/targetbranchingithub (eg. usually refs/for/master)

1 Like