Developing with Git

This document explains the branch mechanism Hazelcast uses and how to push changes on Github.

Git Terms

master :  Main code branch. Usually, branches are created out of master. But, you should not do your work directly in the master branch and should create new branches frequently (e.g. new branches for each feature/ticket you are working on). When these works are completed, merge those back into the master branch. Branching and merging in Git should be a part of your daily development practices.

origin: Default remote repository (at GitHub) that all your branches are pulled from and pushed to. This is defined when the initial git clone command is executed.

upstream: This is 'THE" hazelcast repo at github.com/hazelcast/hazelcast.

Where Is Hazelcast Code?

All Hazelcast repositories (repo) are located at github.com/hazelcast/

Hazelcast has two main projects:

  • Hazelcast IMDG  - 
  • Hazelcast Jet  - 

There are also numerous modules. 

The development process is the same: you work off a fork and make Pull Requests.

We will describe the development process from the perspective of the main Hazelcast IMDG project - 

Branches

Three branches are used. 

  • master branch is the main development/feature branch.
  • maintenance-3.x will be the bugfix/patch branch for latest 3.x release

During development Hazelcast produces Snapshot releases periodically on which ongoing efforts are performed. These snapshot releases are similar to full ones, except that they might not include all the bits included in a full release (such as updated documentation). Snapshot releases are named as <release number>-SNAPSHOT.

Setting up your Github Account

To work with the Hazelcast sources, you need to have a Github account. Go to https://github.com, pick a username and password and type your e-mail address. Press Signup for Github. Select Free for plan and then press Finish Signup button and you are done.

Setting Github Authentication

Github needs to know that your computer is allowed to communicate with your Github repos. For that, we need to set up an authentication and that is done through an SSH key. Follow the tutorial located at the below link to setup your keys.

https://help.github.com/articles/generating-ssh-keys

Forking Hazelcast

Go to github.com/hazelcast/hazelcast and press the  button on the right top of the screen. You will get a popup asking where to fork the repo. Select here the one with your Github account name, in my case @pveentjer.

This will create a new repository called origin. Hazelcast repository we will call is master.

Forking the repository will take some time. Once it is done, you will see your own Hazelcast fork in Github. On the middle right of the screen, you see a button next to the text field under HTTPS clone URL, as shown below.

Copy the URL to your clipboard by clicking on this button and open a console. Go to a location where you want to check out your origin repository and type the following:


Make sure you replace the URL by the one in your clipboard and press enter. Now Github will checkout your origin repository:


Once that is finished, change directory to hazelcast.


The next step is to register the real Hazelcast repository under the name master by typing the below commands:


You will see the output similar to the following:


To see which branches there are in total, you can use the below command:


Now you have a fully working git setup.

How To Get Changes

Depending on who you ask we have four ways to get changes that were made to Hazelcast master:

Note: prune is used to remove remotely deleted refs from local.

Development Life Cycle

Hazelcast uses a pull-request based development. Bug fixes/improvements/features coming from the developers should be pushed to developers` own git forks first, and then a pull request must be sent to merge those pushed items with the main repository. There is no direct push to main repository branches.

This pull-request mechanism requires to work on two separate remote repositories:

  1. The default remote one with the name origin which is the fork of main repository (copy of the main repository placed at your Github account)
  2. And the other one which is the developer`s own repository as remote

Below flow is the main development cycle of Hazelcast:











Adding a New Feature To master Branch

In this section, we are going to create a new feature. We begin by checking out the master branch since we want to implement this feature on the master branch:


If you think that your feature/fix is complete, you can go to your Github page and create a pull request. 

Once the other developers see the pull request, they can merge your changes into the upstream branch. If your changes are rejected, it could be that you need to solve problems like programming mistakes. You can add new commits to an existing pull request, but it is recommended adding more commits on your existing branch and pushing them to origin. 

Adding a Commit To an Existing Branch


Make changes and then:

About Branches

You can give branches any name you want in theory, they are yours. You should make branches for every feature. 

---------------------- OLD----------------------------

How To Apply Local Changes To Branch

If there are any changes not pushed yet:

  1. Save your changes into stash
  2. Get the latest code from the main repository
  3. Pop from stash and apply your changes to branch

Above steps translate as below commands, in the written order:


3. Create branches for each work. When, for example, you are working on a bug fix on version 3.0:

git checkout -b fix/3.0/<ticket number> origin/maintenance-3.x


OR, if you have a local branch for maintenance-3.x:

git checkout -b fix/3.0/<ticket number> maintenance-3.x


OR,

git checkout maintenance-3.x
git checkout -b fix/3.0/<ticket number>


4. Perform your work in your new branch. Ensure you get a clean build locally and your changes pass checkstyle and findbugs verification:

mvn -Pcheckstyle,findbugs -DskipTests clean install


5. Commit your changes and push to your own repository;

git commit <changed/worked on file>

git push <repo name> fix/3.0/<ticket number>



6. After changes are pushed, you should browse your newly pushed branch on Github website (e.g. https://github.com/<your username>/hazelcast/tree/fix/3.0/<ticket number>) and send a pull-request. For information on sending pull requests, please see https://help.github.com/articles/using-pull-requests.

Who will Merge the Pull-Requests

Pull-requests should be reviewed and merged by module/feature maintainers. Of course, "at least one" other reviewer's approval is required before merge.

Reviewers should:

  • examine the code,
  • look for typos,
  • check the existence of tests, javadocs, etc. 
  • comment about their approval or missing things and errors directly to the pull request. 

A pull-request can be updated by pushing additional commits to the same branch.

When to Send a Pull-Request - When to Push Directly

  • If the commit is related to a bug fix, patch, Github issue, customer issue, improvement, and a new feature then a pull request is required.
  • If the commit is not related to none of above, but spans multiple code files (like a large refactoring) then a pull request is required.
  • If commit includes changes in modules those are not maintained by the committer, then a pull request is required.
  • Other than these, for single or a few file refactorings, test improvements, test additions, javadoc and document updates; pull request may be optional.