Page tree
Skip to end of metadata
Go to start of metadata

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?

Hazelcast main repository (repo) is located at github.com/hazelcast/hazelcast.

Branches

Three branches are used. 

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

To improve the release process and before an actual release, 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 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

Setting Personal GIT Repository

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:

git clone https://github.com/pveentjer/hazelcast.git

 

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

Cloning into 'hazelcast'...
remote: Counting objects: 128756, done.
remote: Compressing objects: 100% (41180/41180), done.
remote: Total 128756 (delta 64545), reused 128740 (delta 64530)
Receiving objects: 100% (128756/128756), 28.32 MiB | 1.20 MiB/s, done.
Resolving deltas: 100% (64545/64545), done.

 

Once that is finished, change directory to hazelcast.

cd hazelcast

 

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

git remote add upstream https://github.com/hazelcast/hazelcast.git
git fetch upstream

 

You will see the output similar to the following:

From https://github.com/hazelcast/hazelcast
 * [new branch] maintenance-2.x -> upstream/maintenance-2.x
 * [new branch] maintenance-3.x -> upstream/maintenance-3.x
 * [new branch] master -> upstream/master
 * [new tag] v2.6.1 -> v2.6.1
 * [new tag] v2.6.2 -> v2.6.2
 * [new tag] v2.6.3 -> v2.6.3
 * [new tag] v2.6.4 -> v2.6.4
 * [new tag] v3.0 -> v3.0
 * [new tag] v3.0-RC1 -> v3.0-RC1
 * [new tag] v3.0.1 -> v3.0.1
 * [new tag] v3.0.2 -> v3.0.2
 * [new tag] v3.0.3 -> v3.0.3
 * [new tag] v3.1 -> v3.1
 * [new tag] v3.1.1 -> v3.1.1
 * [new tag] v3.1.2 -> v3.1.2
From https://github.com/hazelcast/hazelcast
 * [new tag] v2.6.5 -> v2.6.5
 * [new tag] v2.6.6 -> v2.6.6
 * [new tag] v3.1.3 -> v3.1.3
 * [new tag] v3.1.4 -> v3.1.4
 * [new tag] v3.1.5 -> v3.1.5

 

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

git branch -a

 

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:

git fetch upstream --prune (gets changes but does not apply them)
 
git rebase upstream/master (Chris: local changes must be committed or stashed)
 
git merge upstream/master (Chris: local changes must be committed or stashed)
 
git pull upstream master (Peter)

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:

# check out the master branch if you want to add a feature based on the master branch
git checkout master
# gets the latest changes from the upstream repo to make sure we are fully up to date
git pull upstream master
#create a new branch for the new feature
git checkout -b fix/3.x/myfeature
..make your changes
# adds all our changes to changeset
git add -A
# commit all the changes: they will now be available on our local repo
git commit -m "My changes"
# push our feature to our personal repo
git push -u origin fix/3.x/myfeature

 

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. 

Warning

Please make sure that your pull request is processed quickly. The more time it takes, the more changes there are for conflicts.

Adding a Commit To an Existing Branch

# checks out your branch
git checkout yourbranch

 

Make changes and then:

git add -A
git commit -m "More changes"
git push -u origin yourbranch

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:

git stash save "uncommitted changes"
git fetch origin --prune
git checkout -b maintenance-3.x origin/maintenance-3.x
git stash pop stash@{0}

 

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 works in your new branch and commit your changes:

git commit <changed/worked on file>

 

5. Push your own repository;

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

 

Note

The prefix "fix" can be replaced with "feature", "improvement" or any other explanatory prefix depending on the work you perform. 

 

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.

Important

If you are working on a bug fix, that fix should be committed to the both master and maintenance-3.x branches.

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.
  • No labels
Write a comment…